Troubleshooting

The tool won't open

Opening runs a full check pipeline. If any check fails you get a notification explaining why. Work through these:

• Permission — if Config.Permission.Enabled = true, confirm the player passes. For Type = 'ace', make sure the ACE (animpos.use) is granted with add_ace. For Type = 'job', make sure the player's job is in Config.Permission.Jobs.
• State restriction — you are blocked while in a vehicle, falling/parachuting, swimming (if enabled), dead, in last stand or handcuffed. The notification tells you which state. Adjust the relevant Config.Restrictions flag if the block is unwanted.
• Cooldown — after each use there is a Config.Cooldown (default 15 s) wait. "Too fast! Please wait a moment." means the cooldown is still active.
• CanUse hook — a custom Config.CanUse returning false will block opening. Check for custom logic there.

No notifications appear

This is almost always a backend mismatch. Config.Notify must match a notification system that is actually running:

• ox_lib — requires ox_lib started (the console warns if it is set to ox_lib but ox_lib is not running).
• qbcore — requires QB-Core and its QBCore:Notify event.
• esx — requires ESX and its esx:showNotification event.
• custom — requires a working handler in Config.CustomNotify.

An invalid value falls back to ox_lib and logs a console warning.

The keybind does nothing

• Confirm Config.Keybind.Enabled = true and Config.Keybind.Default is not empty — the keymapping is only registered when both are set.
• The keymapping is registered on resource start; if you changed the config, restart the resource.
• Check the player hasn't rebound (or cleared) the key under Settings → Key Bindings → FiveM. The command /animpos always works regardless of the keybind.

Text is in the wrong language / English

• Set setr ox:locale "<code>" in server.cfg (use setr so it replicates to clients).
• Use a supported code: en, tr, de, fr, es, pt, ru.
• A missing translation key falls back to English — verify your locale file has that key with the exact same name as in en.json.

Framework features not working / not detected

• Set Config.Framework to match your server exactly (qbox, qbcore, esx or standalone). An invalid value logs a console warning.
• The dead / last stand / handcuffed restrictions only work on qbox and qbcore. On esx and standalone those metadata checks are skipped by design — only vehicle / falling / swimming apply.
• If metadata restrictions still don't trigger on QBox/QB-Core, your framework may store those fields under different keys — adjust Config.Restrictions.MetaKeys.

Character stuck frozen or transparent

The script clears alpha, unfreezes the ped and restores ragdoll on resource stop, so restarting bupa-animpos resolves a stuck state. If an integration left ped scaling paused, the resume export is also called on cleanup.