Documentation

Common Issues

Checks for items, starting attempts, pick wear, the kit, and integrations.

#Console Warns About Missing Items

On start, both consoles print Configured item '<name>' does not exist in your inventory, add it from extras/items for any configured pick, the tension wrench, or the kit item your inventory does not know. Copy the definition from extras/items and restart both resources. For unused items, remove veh_lockpick and veh_advancedlockpick without Vehicle Keys, set Config.Items.kit = false, or switch to hook_pick as described in Setup.

#Attempt Does Not Start

Players see "You need a usable lockpick." when they have no pick from Config.Items.lockpicks with durability left, or the slot passed to PrepareLockpick holds none. A snapped pick stays in the inventory at 0 durability and can no longer be used; set Config.Items.removeBroken = true to remove it instead. "You need a tension wrench to pick this lock." means the player has no tension_wrench, which every attempt needs.

"Could not prepare your lockpick. Try again." means the server did not answer in time or could not write the pick's metadata; check the server console for inventory errors.

#Lock View Does Not Open

"Stand still on foot before opening the lock preview." means the player is dead, in a vehicle, or moving. "Close your current camera or menu before opening the lock preview." means another menu or script camera is open; keep close = true (ox_inventory) or shouldClose = true (qb-core) on the pick items so the inventory closes on use. "Could not load the lock preview. Check the resource stream files." means the lock models did not load, so reinstall the resource with its stream folder intact.

#Pick Does Nothing When Used

Only picks in Config.Items.usable are usable, and each must also be in Config.Items.lockpicks, or the console prints Config.Items.usable '<name>' is not in Config.Items.lockpicks, it is not made usable. Using a pick in a vehicle or during an attempt does nothing, and if another resource makes the same item usable, remove it from Config.Items.usable. Players see "There is nothing to pick here." when no resource offers a lock within reach, 2 metres by default.

#Attempt Closes by Itself

The attempt is cancelled when the player takes damage, ragdolls, falls, dies, enters a vehicle, moves more than 1.5 metres, or takes longer than four minutes. It also closes when the anchored entity is deleted or the calling resource stops or cancels it. A cancelled attempt still takes Config.Items.minDurabilityLoss from the pick.

#Lock Floats in Front of the Player

When walls, vehicles, or props block the camera's view at every position near the target, the lock floats in front of the player instead. This is expected in tight gaps.

#Lock Opened but Nothing Unlocked

Integrations act on the server-validated result, not on what the client saw. A win faster than the fastest possible solve, or with no pick durability left, is treated as cancelled and prints Rejected a lockpick win from player <id> after <ms> ms to the server console. Your own integration must read ConsumeLockpickResult once, within 30 seconds of the attempt ending.

#Pick Icons or Wear Look Wrong

Copy every icon from extras/items/images/256/, and keep images in the pick's Config.Items.lockpicks entry. For inventories that do not read metadata.image, edit GetLockpickWearMetadata in server/unlocked/functions.lua. Picks must not stack, so use the definitions from extras/items and remove any existing stackable lockpick entry.

#Lockpick Kit Does Nothing

The kit item must exist in your inventory, and Config.Items.kit.lockpick must be in Config.Items.lockpicks, or the console prints Config.Items.kit.lockpick '<name>' is not in Config.Items.lockpicks, the lockpick kit is disabled. Players see "You don't have room for the contents of the lockpick kit." when they cannot carry the picks and wrench.

#Practice Command Is Missing

/lockpicktest is only registered with Config.Settings.debug = true, so restart the resource after changing it. The player also needs one of the permissions in Config.Settings.commandPermission.

#Other Resources Do Not Use the Minigame

Keep the folder name zyke_lockpick and start it before the resources that use it. For Vehicle Keys, set lockpicking.minigame to "auto"; see its Lockpicking guide.