Common Issues
Start with the current Installation and check both server-console and client F8 errors. For QB/QBX integrations, see QBCore / Qbox.
Enable useful diagnostics
Set debug = true in config/shared/config.lua, restart Carlock, and reproduce the issue once. The client/server startup summaries report effective features and providers. Warnings and errors remain visible when debug is off; client GiveKeys terminal failures also produce warnings without debug.
Record the resource version, framework/inventory/provider names, effective key mode, exact action, and relevant log messages. Disable debug again after investigating.
Physical keys are disabled or locksmiths are missing
Metadata mode falls back to virtual keys when no inventory bridge is registered. Start your supported inventory before Carlock and verify the effective inventory and metadataKeys startup values. Locksmith registration also requires locksmith.enabled and a non-empty locksmith.locations list. Confirm the selected interact provider is running.
A key works with U, but inventory use fails or consumes the item
Check the exact provider block in _invItems/data.lua, the item's plate metadata, and unique/non-stackable settings. Ox requires consume = 0 and its server.export; CodeM uses its own usable route, not the Ox export. TGIANN requires the editable-function snippet and nonconsuming definitions, including admin overrides. Remove duplicate use handlers.
Do not name a key item the same as a lockpick/hotwire tool. Carlock skips conflicting key-use registration to avoid replacing the tool handler. Restart after fixing definitions and inspect registration warnings.
GiveKey returned true, but the player has no key
Client GiveKey/GiveKeys returns whether the request was queued/sent, not whether it succeeded. Check the terminal warning for missing vehicle, network readiness, range, bucket, ownership, or inventory failure. Set the final vehicle plate before requesting a key and allow the vehicle to become network-ready. keyGrantTimeout is a bounded deadline, not a grant bypass.
Client self-grants are ownership-checked, with a configurable exception for eligible unowned scripted vehicles. A plain client event cannot grant arbitrary plates. Integrate an authorized server purchase/spawn flow with the server export when appropriate; its optional third argument is a model, not an entity handle.
GetAllKeys is empty or does not include inventory keys
GetAllKeys returns a virtual-key map or false, not a physical inventory list. Use HasKey(plate) on the client or HasKey(playerId, plate) on the server to test possession in either mode. Client lookups cannot query another player's keys.
The give/manage menu or OpenVehicleControls export is missing
ManageKeysMenu is registered only in effective virtual-key mode with management enabled. The give/manage commands are also virtual-mode features. GiveKeyMenu is not exported in V3.
OpenVehicleControls is registered only with vehicleControl.enabled = true. A disabled feature can mean a missing export rather than a callable export returning false. Also check that Carlock completed initialization before an integrating resource calls it.
The engine toggle does nothing, or a police vehicle starts without keys
The standalone /toggleengine / G binding is disabled by default. Enable engine.toggle.enabled to install it; the UI engine control is separate.
ignitionBypass.jobs includes police by default and bicycle models are also bypassed. Bypass permits automatic ignition, not remote locks or the control menu. Check for competing resources changing engine/lock state.
A custom vehicle uses the wrong key/tool or cannot be lockpicked
Use vehicleAccessProfiles.modelOverrides with the exact spawn name and an existing case-sensitive profile name, such as highEnd. Avoid duplicate class assignments. Pass the vehicle model to trusted server grants so the key profile can be resolved.
For a model with a known class, lockpick.difficulties[class] takes precedence over the profile fallback; an omitted class is blocked. Ensure the resolved key/tool items exist in the inventory. A vehicle label override changes display text, not security policy.
The tracker cannot find a vehicle or trigger its alarm
The profile must enable tracker, the player must still hold the key, and the vehicle must be spawned in the same routing bucket. Stored/despawned vehicles cannot be located. Remote alarm application depends on a valid network owner and acknowledgement. Locking remains limited by locking.distance even when locating succeeds.
Search, hotwire, or NPC key actions are unavailable
Search/hotwire use the no-key driver flow and their feature switches. Search is not available again after that plate was searched in the current runtime; hotwire attempts are limited. Check profile item requirements and tool availability.
NPC assistance requires an allowed ESX/QB/QBX job name; Ox/custom bridges without that contract deny it. NPC key flows exclude owned/already-claimed vehicles. Dead-NPC pickup belongs to the original initial-resistance claim, not every corpse on the map.
No police dispatch call appears
Check policeAlerts.enabled, provider startup/selection, chance settings, configured police groups, and rate limits. Acting players in those police groups are excluded from the alert path. Illegal locksmith services use their own chance.
For Wasabi MDT V2, confirm both the wasabi_mdt_v2 resource-state check and the wasabi_mdt:CreateDispatch export contract are satisfied. Unsupported/stopped provider selection falls back to internal dispatch, but an error after submission is not automatically retried. External systems own their recipient filtering. See Integrations.
The UI is blank, or a custom minigame immediately cancels
Confirm the release contains ui/build/index.html and its referenced assets, the resource name is unchanged, and client NUI errors are absent. Do not deploy only the UI source directory.
Custom minigame hooks ship as return nil placeholders. Implement the hook before selecting provider = 'custom', return a boolean for a completed game, and use cleanup/cancellation support. Keep minimum duration below the allowed duration.
Database ownership initialization fails
Verify oxmysql, the connection, and the framework's existing ownership schema: ESX owned_vehicles, QB/QBX player_vehicles, or Ox vehicles. Carlock does not provide a separate SQL installation schema. Custom ownership tables require integration work; do not treat a failed lookup as proof that a vehicle is unowned.