Troubleshooting

Resource conflicts

• jg-advancedgarages must be disabled. legacy-garages provide()s the jg-advancedgarages resource name; two resources cannot provide the same name at once. Move the original to resources-disabled.
• Do not rename this resource in fxmanifest — third-party scripts (vms_housing, rcore_police, lb-phone) rely on the jg-advancedgarages name alias to keep working.

Database

• This resource depends on JG's exact player_vehicles columns (in_garage, garage_id, impound, impound_data, nickname, job_vehicle, gang_vehicle, damage, etc.). Schema changes to that table will break compatibility — there is no migration path in the other direction.
• sql/loadouts.sql uses CREATE TABLE IF NOT EXISTS and is not auto-applied — import it manually before first launch, or legacy-garages:saveLoadout will error on a missing table.
• legacy_garages_loadouts has a composite primary key (citizenid, garage, vehicle) — re-saving a loadout overwrites the previous row instead of inserting a new one. config is stored as unvalidated LONGTEXT JSON, and citizenid has no foreign key constraint (orphaned rows can persist after character deletion).

Config gotchas

• Renaming a Config.Garages key changes the garage_id value expected in the database — existing rows referencing the old key will point at a garage that no longer exists unless you run a manual UPDATE.
• Config.Finance only works if jg-dealerships is running and exposes makeFinancePayment; enabling it without that resource will error when a financed vehicle is opened. jg-dealerships exposes no single payoff export, so financePayoff loops payments (max 60) and can leave partial progress if funds run out mid-loop.
• trunkLoadout/gloveboxLoadout item ids are validated against ox_inventory at boot — an unknown item id is a startup error, not a silent no-op.
• Config.CheckVehicleModel = true will silently refuse to spawn vehicles whose stored DB model doesn't match — bulk-imported vehicles with mismatched model columns will fail to spawn until fixed or the check is disabled.
• Config.AllowInfiniteSpawns = false can leave a vehicle permanently "stuck out" if a previous session never marked it returned (e.g. a crash).
• Config.ImpoundReleaseExternal being set to a resource name changes the release UX to just show a message — if that external resource isn't actually running impound releases, players will have no way to release vehicles.
• Config.UseTarget = true requires the resource in Config.Target (default ox_target) to be started before legacy-garages.
• Mixing up vehiclesType ('owned' vs 'spawner') on a job garage entry changes its entire interaction flow.
• Config.ClassTypes only maps a subset of vehicle class IDs — unmapped classes have no defined garage type, affecting where such vehicles can be stored.

Runtime / restart behaviour

• On every resource start (including a manual restart legacy-garages), all vehicles with in_garage = 0 and impound = 0 are force-set back to in_garage = 1 after a short delay — any vehicle legitimately left outside (e.g. tracked via valet) is silently pulled back in, with no return fee charged despite referencing JG's fee behavior in comments.
• The jg-advancedgarages:server:register-vehicle-outside compat handler only updates in_garage — it does not despawn the world entity or validate garage_id, and combined with the restart-recovery behavior above, a vehicle "checked out via valet" will be silently pulled back on next restart.
• reserveUniquePlate/used-plates tracking is in-memory only and resets on restart — plate collisions are only prevented within a single server session (plus a DB check against stored vehicles).
• getMileageUnit() caches lazily on first successful call because jg-vehiclemileage is expected to start after legacy-garages; reversing load order can set (or permanently fail) the cache at the wrong time.
• GetPlayerGangName and job-grade label lookups call qbx_core exports directly, bypassing legacy-lib's framework bridge — swapping frameworks requires patching these two functions in sv-main.lua specifically.

Client-side gotchas

• The showroom preview vehicle is not frozen and keeps physics (only collision is disabled) — this is required for extras (e.g. lightbars) to re-attach correctly. Don't "fix" apparent drift by freezing it; the camera loop already pins its position every frame.
• Toggling a showroom extra fully re-spawns the preview vehicle (a new one is created before the old is deleted) rather than mutating it in place, because SetVehicleExtra doesn't reliably re-attach some extras live.
• SpawnJobVehicle's entry.plate must be the full, server-reserved, session-unique plate — appending anything to it can cause two vehicles to collide and share a trunk/glovebox loadout server-side.
• 'legacy-garages:client:despawn-plate' only trims trailing whitespace when matching plates — differently padded/cased plates elsewhere won't match, and the vehicle will silently fail to despawn.
• StoreVehicle() and the impound form both prefer a realPlate statebag (for legacy-pettycrime fake-plate compatibility) over the visible plate — if you set fake plates via another mechanism, mirror the real plate into Entity(vehicle).state.realPlate or garage integrations will store/impound the wrong plate.
• removeBlips() must be used to clear blips (it stores {handle, coords, group} tables, not raw handles) — passing one of these directly to RemoveBlip is a silent no-op and leaves blips stranded after a restart.
• Storing a vehicle whose type (car/air/sea, from Config.ClassTypes) doesn't match the garage's configured type is rejected client-side with an error notification and never reaches the server.

UI build gotchas

• web/dist is what the game actually serves — the Vite dev server (port 3006) is for local preview only. Run npm run build after every UI change.
• vite.config.js sets build.emptyOutDir: true — every production build wipes web/dist first; don't manually place files there expecting them to persist.
• Tailwind only scans ./index.html and ./src/**/*.{js,jsx} for classes — new UI source files outside src/ won't be scanned for class purging.
• The Vite base option must remain './' (relative) for assets to load inside the FiveM NUI (CEF); an absolute path will break asset loading in-game.