Troubleshooting

Installation, worker, export, and shop troubleshooting for 0r-tattoo_designer

This guide covers the current resource behavior.

The Studio does not open#

Did ox_lib, oxmysql, 0r-tattoo_runtime_assets, 0r-tattoo_designer, and 0r-tattoo_exports start in the correct order?
Is Config.Command.Enabled enabled, and does the player have tattoo_designer.use?
Can oxmysql connect to the database?

add_ace identifier.license:your-license-here tattoo_designer.use allow

The worker does not start or times out#

The host worker requires Node.js 22+ and the executable selected by Config.Worker.NodePath must run successfully. The node_version '22' setting in fxmanifest.lua selects FiveM's embedded bridge runtime; it is a separate Node boundary from the host worker.

Set an explicit path when PATH resolution is not sufficient:

Config.Worker.NodePath = 'C:/Program Files/nodejs/node.exe'

For a child-process permission error, add this before the ensure lines and fully restart the server:

add_unsafe_child_process_permission 0r-tattoo_designer

Projects or tattoo ownership appear to be missing#

Check the oxmysql connection and the presence of:

0resmon_tattoo_designer_schema_migrations
0resmon_tattoo_designer_saved_projects
0resmon_tattoo_designer_player_applied_projects
0resmon_tattoo_designer_apply_jobs
0resmon_tattoo_designer_saved_project_shares
0resmon_tattoo_designer_player_tattoos

If you use a custom multicharacter system, modules/identity.lua must return a stable character-specific identity.

Unsaved Studio drafts are process memory and are cleared after a resource or server restart. Only explicitly saved projects persist in MySQL. If a saved project is missing, check the character identity and migration state in addition to the database connection.

The build succeeds but the tattoo is not visible in-game#

Did 0r-tattoo_exports start after the designer?
Did you run Export Reload after building or deleting a project?
Does resource.0r-tattoo_designer have command.refresh, command.ensure, command.start, and command.stop ACE permissions?
Is 0r-tattoo_runtime_assets still running?

command.restart is only required when a restartable appearance provider must also be restarted.

If the designer resource was restarted while a player was connected, fully close and relaunch the FiveM client before testing custom overlays again.

Export Reload is denied#

The following lines must appear before the resource ensure lines:

add_ace resource.0r-tattoo_designer command.refresh allow
add_ace resource.0r-tattoo_designer command.ensure allow
add_ace resource.0r-tattoo_designer command.start allow
add_ace resource.0r-tattoo_designer command.stop allow
add_ace resource.0r-tattoo_designer command.restart allow

FiveM's ensure command calls start internally. If you grant command.ensure without command.start, the console can show Access denied for command start, followed by export_resource_start_timeout after 15 seconds. Grant these permissions to resource.0r-tattoo_designer; group.admin command allow does not grant them to the resource.

Check the active permissions in the server/txAdmin console:

test_ace resource.0r-tattoo_designer command.start
test_ace resource.0r-tattoo_designer command.ensure

Both checks should return true. If a check returns false, save the missing ACE from the list above in server.cfg or the permissions file it executes. To apply the ACE to the running server, run the same add_ace line in the server/txAdmin console. Repeat the checks and retry Export Reload after both return true.

Grant command.restart only when you also restart an appearance provider. If the Illenium companion file cannot be written, also add:

add_filesystem_permission 0r-tattoo_designer write illenium-appearance

Images or remote files do not load#

Check config/private.lua for the Discord webhook URL or FiveManage API key and confirm that the provider is reachable. Remote asset and preview URLs must support public HTTPS GET, the expected MIME type, and CORS for the cfx-nui-0r-tattoo_designer origin.

Preview data URLs default to 512 KiB per zone and 2 MiB total. A request-timeout, provider quota, CORS, MIME, or size failure can reject the operation without changing the last accepted preview. Never send credentials in support messages, screenshots, or public repositories.

Template Images do not open#

There is no offline template catalog. Verify that the active manifest at catalogs//catalog.json is reachable, thumbnails and assets allow NUI CORS, all URLs refer to the same immutable catalog version, and each file matches its manifest SHA-256. Custom catalog mode never falls back to the vendor catalog.

Payment or professional session fails#

For built-in payment, QBX, QB-Core, or ESX must be running and the customer must have enough cash. For a custom economy, enable USE_CUSTOM_PAYMENT and implement the four handlers in modules/payment.lua. Check the Professional Access rules or the custom access function for artist authorization.

Rendering and upload happen before charging. Preparation, payment, or the canonical ownership write can fail without creating ownership. After canonical commit, runtime or artist-payout failure preserves customer ownership. There is no refund workflow or retry of a charged apply job; inspect the server log and payment provider state when a failure includes no_refund=true.

Custom Tattoo Designer tattoos disappear after Illenium customization#

Illenium's native tattoo setter clears all ped decorations and then restores only the tattoos in its own appearance.tattoos snapshot. Custom Tattoo Designer overlays are maintained by 0r-tattoo_designer and need the post-exit compatibility hook.

Confirm that illenium-appearance/game/customization.lua emits:
lua
```
TriggerEvent("illenium-appearance:client:appearanceApplied", "customization_exit")
```
The event must be after the final setPlayerAppearance or setPedTattoos call in client.exitPlayerCustomization.
Confirm that the delivered 0r-tattoo_designer/client/init.lua listens for illenium-appearance:client:appearanceApplied.
Fully restart FXServer after changing the Illenium resource, then apply a custom image tattoo and test editor save, editor cancel, and outfit change.
If native Illenium tattoos remain but the custom overlay is missing, the provider hook or the 0r listener is missing; this is not fixed by adding the custom overlay to Illenium's appearance.tattoos data.

Illenium tattoos do not update#

Confirm that Config.AppearanceIntegration contains the actual illenium-appearance resource name and that the resource is running. Run Export Reload and test add, remove, provider reapply, and reconnect behavior.

FXServer DLL compatibility error or crash#

If the error occurs before Tattoo Designer logs appear, update FXServer to a current stable artifact. Older artifacts can be incompatible with current native or DLL components.

Integration button is hidden#

Check External Integration. Start the separate resource with a compatible main resource, configure the selected provider with a key and model, and confirm that the player satisfies its access policy. Previous generation settings in the main resource no longer enable the integration. Restart the integration resource after changing its configuration.