What goes wrong most often, what it actually means, and what to do about it. Most of these are configuration, not faults — and the script says which: the startup checks in the server console, tattoo_shop for a studio, and tattoo_ink_debug in F8 for what a client sees. Run the one that matches before opening a ticket.
Installation and Startup#
The console repeats "server.cfg is missing required permissions"
The five add_ace lines are missing. Player tattoos are unaffected, but catalog exports are refused until they are there, and admins see a notice when they open the panel. Add them above ensure qs-tattoo-creator — or paste them into the server console, which fixes it right away:
add_ace resource.qs-tattoo-creator command.ensure allow
add_ace resource.qs-tattoo-creator command.start allow
add_ace resource.qs-tattoo-creator command.stop allow
add_ace resource.qs-tattoo-creator command.restart allow
add_ace resource.qs-tattoo-creator command.refresh allow✗ Preview collection
qs-tattoo-preview is not running. It ships in the download next to qs-tattoo-creator; put it back if it is missing and add ensure qs-tattoo-preview above ensure qs-tattoo-creator.
✗ Ink slot pool — "rewrote it"
The collection every worn tattoo is drawn into did not match what the script expects — usually after an update — so it was rewritten. The game only reads it when qs-tattoo-preview starts: restart the server once, or restart qs-tattoo-preview while nobody is online. Until then no tattoo can be shown. If the line says it could not rewrite it, the qs-tattoo-preview folder is missing or not writable.
✗ C# encoder — players see "The tattoo machine is out of order"
The script ships a small C# component in server/dotnet/ that runs on the server's built-in Mono runtime. When it fails its self test, players cannot pay for tattoos at a studio and catalog exports cannot be made. Re-copy the whole qs-tattoo-creator folder — the server/dotnet/templates files must be there — and make sure your server artifact is current. A ✗ File helper line is the same component not answering at all.
✗ Data folder or ✗ Data writable
The script could not create or write qs-tattoo-data next to itself, so no tattoo can be saved. On Linux, make sure the user running the server owns the resources folder. If the line says the folder "could not be started", restart the server once.
✗ Studio undress list
Config.Studio.Reveal is missing from your custom/config.lua — typically an older copy kept over an update. The studio then opens without taking any clothing off. Copy the block from the custom/config.lua that shipped with your version.
"could not create qs_tattoo_settings" or "the server never sent its settings"
The database user cannot create tables, so settings cannot be saved and the server runs on the shipped defaults. Give the user the right to create tables, or run [sql]/database.sql by hand, then restart.
"You don't have permission to do that." on /tattoocreator
Admins are whoever your framework calls an admin: on ESX a group in Config.AdminGroups, on QBCore and Qbox the god or admin permission or the command ace, standalone the command ace. An ace added to server.cfg needs a server restart, and must be for the same account you are playing on.
Tattoos come back slowly after a clothing change, or the wrong appearance script is used
The appearance script starts after Tattoo Creator, so it was not detected. Move its ensure above ensure qs-tattoo-creator. With two appearance scripts installed, name the one players use in Config.AppearancePin.
Studios and the Studio#
Nothing appears at a studio — no NPC, no prompt
A studio only exists while a player is inside its area. Run tattoo_shop in the console: no studio area (nothing will spawn) means the area was never drawn, and the F8 console says the same. Draw it in the studio's form and save.
"You need a tattoo artist for that."
Settings → Shops → Self service is off, so customers cannot use the NPC alone. Switch it on, or have an artist invite them.
"This shop is closed."
The studio is set to Closed — in its form in the admin panel, or by its owner in the management menu → Settings → Open to customers.
"The shop is out of supplies."
A player-run studio ran out of ink, needles or gloves. Order more from the management menu → Supplies and collect the crate, or switch Settings → Shops → Block when empty off to make supplies cosmetic.
"The studio only works with the standard character models."
Tattoos are GTA ped decorations, which only exist for the freemode characters mp_m_freemode_01 and mp_f_freemode_01. A player using another ped model cannot be tattooed.
"You are too far from the shop."
The studio opens within 12 m of its tattoo spot, or of the NPC when there is none. If the spot was placed far from the NPC, move one of them.
The character keeps some clothes on in the studio
A clothing pack replaced the base game's bare-body clothing, so the studio swaps one garment for another. Set the numbers that pack left bare in Config.Studio.Reveal — see Integrations.
A design disappeared when the studio was closed
Closing the studio discards anything not paid for. The History tab keeps the last 80 things a player put on their body, paid or not, and brings any of them back with one click.
Tattoos on the Character#
A tattoo disappears after changing clothes
The clothing script cleared it and nothing put it back. Check that the right appearance script was detected (see above); with illenium-appearance set Config.RCoreTattoosCompatibility = true in its config. If your own script rebuilds the character, call exports['qs-tattoo-creator']:ReapplyTattoos() when it is done. The watchdog in Settings → Re-apply catches anything else within seconds.
Other players cannot see my tattoo
Run tattoo_ink_debug in F8 on the player who cannot see it. Its last line names the cause: a collection that is not mounted (restart qs-tattoo-preview once while the server is empty), pictures still on the way, or the game refusing a decoration. Tattoos are shown within the Show radius (45 m); in a very crowded spot the farthest wearers are shown last.
"This character already has ink on the maximum number of body parts."
Settings → Ink & textures → Body parts per character limits how many of the six body parts may carry ink at once.
"Too many tattoos on this zone."
A body part holds at most 8 tattoos. Combine some into one design with layers, or remove one.
"This zone is still being inked, try again in a moment."
The previous change to that body part is still being saved. Wait a second and pay again.
"The tattoo could not be saved" or "The server could not store the image"
The server could not write into qs-tattoo-data. The startup checks say why; it is almost always folder permissions. The player's money is given back automatically.
Player-Run Studios#
The tattoo spot only says "Clock in from the management menu before you can tattoo"
Clock in from the management menu first. A rank without Open the management menu — the default Apprentice — can never clock in: give the rank that permission, or switch Settings → Shops → Clock in to tattoo off.
Inviting a customer does nothing, or says they are too far
The customer must be within 4 m of the artist, not already in another session, and the spot must be free — one session per studio at a time ("That spot is in use."). The artist must be on shift at this studio.
"You do not work here." or "Your rank does not allow that."
The player is not on that studio's staff, or their rank lacks the permission for that tab or action. Ranks are per studio. tattoo_shop lists who is on staff and on shift.
"This studio is not a company."
The studio's Company switch is off, so it has no owner, staff or management menu. Switch it on in the studio's form.
Staff were not paid
Wages come out of the studio's till every payroll interval, only to staff on shift at that moment. A till that cannot cover a wage pays nothing and tells the worker "The till could not cover your wage." — deposit money into it.
"This shop has no supply delivery point set."
Place the Supply delivery point in the studio's form; orders cannot be placed without it.
Nobody can pick up the supply crate
Only staff of that studio can collect it, within 2 m. A crate that arrived while nobody was nearby appears as soon as someone walks into the studio.
Images and the Catalog#
An image link is refused
Message | Means |
|---|---|
Images from that site are not allowed. | Allow any host is off and the site is not in |
That link points at the server itself or its local network… | The link leads into your own machine or LAN. Always refused. |
Could not download the image. | The site did not answer, or refused the server. |
Unsupported image format. | Only PNG, JPG, WEBP and GIF are accepted. |
Image links are disabled. | Settings → Images → Allow image links is off. |
A catalog export is refused
The add_ace lines are missing — the admin sees a red notice and the lines are printed in F8 and in the server console — or the C# component failed its startup check.
Players crashed during a catalog export
Exporting, replacing or deleting a catalog entry restarts qs-tattoo-data, which can crash players who are loading in at that moment. Do it on an empty server. Player tattoos never need it.
An exported tattoo does not show in the appearance menu
Check that the script is listed in server/custom/appearance.lua and that the file named there is one it loads. The server console says when it could not update that file.
Error Keys#
Every refusal is a locale key, so the same failure reads in each player's own language. The ones you are most likely to meet:
Key | Means |
|---|---|
| The C# component failed its startup check. See above. |
| The |
| The studio is out of supplies. |
| The studio is closed. |
| Customers cannot use the NPC alone; they need an artist. |
| The player is too far from the studio, or the customer from the artist. |
| The player cannot afford it — in the account they chose. |
| Not on that studio's staff · the rank does not allow it. |
| The artist has to clock in first. |
| The studio's tattoo spot is already in use. |
| The studio's till does not hold that much. |
| Body parts per character reached · 8 tattoos on that body part. |
|
|
| Too many uploads in a minute. Wait a moment. |
| The server did not answer in time. Usually a slow database. |
Still stuck? Open a ticket and include the startup lines from your server console, the output of
tattoo_shoportattoo_ink_debugif it is about a studio or a visible tattoo, and your framework and appearance script with their versions.