Troubleshooting
How to capture the lation interact debug report, answers to common problems, and what each console message from lation interact means.
The debug report
When an interaction misbehaves, have the affected player record a report while they try it, and paste it in your ticket.
Type /interact_debug in chat, or interact_debug in the F8 console. It records for 20 seconds. Add a number, such as /interact_debug 45, for 5 to 120 seconds. Run it again while it records to stop early.
Try the interaction that misbehaves.
When it finishes, open F8 and copy everything from the REPORT (paste everything from here) line to END OF REPORT. Every line starts with [interact_debug].
The report holds:
| Section | What it shows |
|---|---|
| Environment | The lation interact version, game build, detected framework and inventory, ox_lib state, language, whether ox_target, qb-target, qtarget and lation_ui read as started, and the main config values. |
| Player | Position, whether they are in a vehicle, whether the layer is hidden and why, NUI focus, pause menu, whether the interact key is held, and the player's groups with grades. |
| Registrations by resource | Every resource that registered something, how many points, zones, entities, model and global registrations, and whether it came through the native API (native), the ox_target bridge (ox) or the qb-target bridge (qb, which qtarget scripts use too). |
| Anchors within 15 m | Up to 25 interactions near the player, nearest first, each with whether it was last seen clear or blocked, and each option marked VISIBLE or hidden with the reason. |
| Crosshair samples | Once a second: what the aim is on, whether a model registration covers it, and which interactions the aim was on, nearest the aim first. |
| Engine trace | Up to 150 decisions: focus changes, sight checks, what was shown, activations, the interact key and the layer being hidden. |
| Recent errors | The last 10 errors, including ones from before the capture started. |
Reasons an option can show as hidden:
| Reason | Meaning |
|---|---|
passive: interact key not held | The option is passive and the interact key wasn't held. |
groups gate, items gate, items gate (any of) | The player lacks the job, gang or items. |
state gate: <key> unset, state gate: <key> mismatch | The entity's statebag value isn't what the option wants. |
state gate: no entity, state gate: a building has no statebag | The option has a state check on something with no statebag. |
canInteract returned false, canInteract error: ... | The script's own check said no, or raised an error. |
script canInteract returned false (distance 1.20) | A bridged script's own check said no. |
distance 3.10 > 2.0, zone distance 3.10 > 2.0 | A bridged option is further away than its distance. |
bone <name> missing on this entity | A bridged bone option on an entity without that bone. |
qb job/gang/item/citizenid gate | A qb-target or qtarget option's job, gang, item or citizen id check failed. |
The layer can show as hidden for pause, nui, progress, dead, cuffed, or a script's tag: the one it passed to suppress, ox_target from ox_target's disableTargeting, or qb-target from qb-target's AllowTargeting.
Common problems
A script's targets don't show at all
Check the report's registrations list. If the script isn't there, it most likely started before lation_interact; move ensure lation_interact above it and restart the whole server. Make sure ox_target, qb-target and qtarget are not running too.
One option is missing
Find it under anchors in the report; the reason is printed next to it. An option an ox_target or qb-target script registered with a distance shows only within that distance of the thing.
The card doesn't open though the player is close
The player has to look at it: the middle of the screen has to pass through the thing, or within 0.4 m of a spot a script put down. It also has to be in view. Walls and objects in between hide it (glass doesn't), and the report's anchor line says seen: BLOCKED when that is the cause. A list of several opens on E, or a click while holding Alt.
Only the first row of a list can be used
Rows without a key of their own are run by E only while highlighted, and the highlight starts on the first row and moves only with the mouse. Players hold Alt and click the other rows. Options from ox_target and qb-target scripts never have keys. With the native API, give each option a key; see keys and holds.
Nothing shows from inside a vehicle
From a seat, interactions on other vehicles, peds, players and objects hide by default, and so do the options on the vehicle the player sits in. See Config.InVehicle and Config.IncludeOwnVehicle under vehicles.
Interactions vanish for a moment
Something is hiding the layer: the pause menu, another resource holding NUI focus, a running progress bar, the player being dead or cuffed, or a script's tag. The report's player line says which. Each automatic reason can be turned off in Config.Suppress.
Cuffed players can still interact
Detection reads the Qbox and QBCore ishandcuffed metadata and the standard restrained animations. If your cuff script works differently, adapt IsPlayerCuffed in bridge/client.lua, or have the cuff script call exports.lation_interact:suppress('cuffed') and release('cuffed').
A moving vehicle or ped shows nothing
Entities moving faster than 3 m/s show nothing until they slow down.
No vehicle door toggles
Check that Config.VehicleDoors isn't false and that server.cfg has no setr ox_target:defaults 0. With Config.VehicleDoors = 'passive' they show only while the interact key is held. Toggles also don't show while the player is seated, while the vehicle is locked, or for a door the model lacks or that is damaged.
Item-gated options never show
lation interact found no supported inventory or framework, and the F8 console says so. See the inventory list in requirements, or add yours to HasItem in bridge/client.lua.
Job or gang options never show
Job and gang checks (groups) read the player from Qbox, QBCore or ESX. On any other framework, ox_core included, lation interact runs as it does with no framework: options with groups stay hidden, and item checks still work through a supported inventory. To add your framework, fill in the -- Add custom framework here spots in bridge/client.lua.
A prop inside an interior can't be targeted by model
If the crosshair samples call it interior collision, the game has no entity there, so nothing can target it by model. Use a point or zone instead.
The hint still says Alt after changing the interact key
The hint's text is ui.hint in locales/*.json and doesn't follow Config.InteractKey or a player's own binding. Edit it there, or turn the hint off with Config.Hint = false.
A label shows as ui.hint or vehicle.toggle_hood
The language file in use is missing that key. Copy it from locales/en.json. See language.
Console messages
Client messages start with [lation_interact]. Errors are red; warnings are yellow.
Server console
| Message | Meaning |
|---|---|
An error has occurred with the resource '...' followed by Please rename the folder to 'lation_interact' | The resource folder was renamed. Rename it back to lation_interact. It repeats every 15 minutes until you do. |
Unable to determine current resource version for 'lation_interact' | The version couldn't be read, so the update check is skipped. This happens when the folder isn't named lation_interact or the version line is missing from fxmanifest.lua. |
Unable to fetch version information from API. | The update check couldn't reach the version server. Harmless. Set Config.version = false to skip the check. |
An update is available for lation_interact | A newer release exists. The next lines show your version and the latest. |
Setup warnings
| Message | Meaning |
|---|---|
Config.ConfirmKey "..." is not a known key name - keyboard confirm is disabled | Use a name from the key names list. |
passive mode is on but the interact key is off (Config.InteractKey and InteractControl) - passive interactions can never be revealed | Turn on Config.InteractKey or Config.InteractControl, or turn off passive mode. |
items conditions need a supported inventory or framework (bridge/client.lua) - gated options stay hidden | No inventory or framework was detected, so item checks can't pass. |
Registration messages
These start with the export's name, such as addPoint:. An error means the registration was skipped and the export returned nil.
| Message | Kind | Meaning |
|---|---|---|
expected a table | Error | The data argument isn't a table. |
label must be a non-empty string when given | Error | label is empty or not a string. Leave it out instead. |
iconColor must be a color string | Error | iconColor on the registration isn't a string. |
at least one option is required | Error | options is missing or empty. |
option N needs a label | Error | Option number N has no label. |
option N iconColor must be a color string | Error | Option N's iconColor isn't a string. |
option N binds unknown key "..." | Error | Option N's key isn't in the key names list. |
option N canInteract must be a function | Error | Option N's canInteract can't be called. |
option N state must be a key name or { key = ..., value = ... } | Error | Option N's state has the wrong shape. |
reveal must be 'ambient' or 'focus' | Error | Unknown reveal value. |
expand must be 'auto', 'manual' or 'smart' | Error | Unknown expand value. |
coords must be a vector3 (or vector4 / { x, y, z }) | Error | coords is missing or unusable. |
radius (number > 0) is required | Error | addSphere needs a positive radius. |
size must be a vector3 (or { x, y, z }) | Error | addBox needs a size. |
entity does not exist | Error | addEntity got a handle that doesn't exist. |
no valid models given | Error | addModel got no model names or hashes. |
option N binds movement key "..." - it will trigger while the player walks | Warning | Option N uses W, A, S or D. It works, but fires while walking. |
option N has a state condition but points/zones have no statebag - it will stay hidden | Warning | state only works on entity registrations. |
... from ...: reveal applies to points and zones; entities reveal on focus | Warning | reveal was set on an entity registration and is ignored. Printed once per resource. |
suppress(reason) needs a string tag | Error | suppress was called without a non-empty string. |
Runtime errors
| Message | Meaning |
|---|---|
onSelect error (resource / label): ... | An option's onSelect raised an error. When it says the handler raised inside that resource, the real error is the SCRIPT ERROR that resource printed just above. |
suppress error: ..., view error: ..., engine error: ... | An internal error. It is also listed under recent errors in the debug report; include the report in your ticket. |
Compatibility messages
Bridge warnings start with ox_target compat: or qb-target compat: and print once.
| Message | Meaning |
|---|---|
nested menus are flattened - opener rows without a handler are dropped, sub-options render in one stack | An ox_target script uses sub-menus. Its options show in one list. |
...: invalid options table from ... - registration skipped (ox_target raises an error here) | The script passed a malformed options table. ox_target would raise an error here too. |
addLocalEntity: no entity with id ... exists (from ...) | addLocalEntity got a handle that doesn't exist. |
addBoxZone: unusable size from ... - using ox_lib's 2x2x2 default | The zone's size couldn't be read, so a 2 x 2 x 2 box is used. |
poly zones are approximated as spheres (centroid + bounding radius) | A poly zone was registered. See the ox_target limits. |
removeZone: no zone with id ... exists, removeZone: no zone named "..." exists | The script removed a zone that isn't registered. |
2D zone centers take the player z at registration time | A qb-target zone was given a center without a height. |
AddCircleZone "...": unusable center - zone skipped | The zone's center couldn't be read. Also for AddBoxZone. |
AddCircleZone "..." has no options - stored but inert | The zone has no options. Also for AddBoxZone, AddPolyZone and AddEntityZone. |
combo zones are approximated as one bounding sphere over their members | A combo zone was registered. |
AddComboZone "...": member centers unknown - zone skipped | None of the combo zone's members expose a center. |
These two start with [lation_interact] alone and print each time:
| Message | Meaning |
|---|---|
qb-target action error (label): ... | A qb-target option's action raised an error. |
qb-target option "..." has no trigger setup (no action/event) | A qb-target option has neither action nor event. |
Still stuck? Ask in our Discord: the people who write the scripts answer.
Last updated
Developers
The lation interact client exports for points, zones, entities, models and entity classes, every registration and option field, the checks, the onSelect and canInteract callbacks, events and feedback.
Changelog
Every lation interact release, newest first, with what it added, changed and fixed.