Troubleshooting & FAQ

Start with the server console. When the resource starts, it says which framework it found, which tables are missing, and which config values it had to fix. See What the console says.

Opening the menu

Problem	Why, and what to do
"You can't open the menu right now."	The player is dead, downed, cuffed or falling, or your own Config.CanOpenMenu rule said no.
"Go to a shop on the map to open the menu."	Opening a shop by command is for admins. Config.CommandsForEveryone = true lets everyone.
"Close the admin panel before opening the menu."	The panel and the menu can't be open at the same time.
The panel says it's only for admins	Add add_ace group.admin zaiders_appearance.admin allow to server.cfg, and make sure your account is in that group. See Commands & permissions.
Pressing E at a shop does nothing	Stand inside its radius: the key on the sign lights up when E works. Check the shop exists in the panel's Shops, and that Config.Shops.key is 38 (E).
Two clothing menus open at once	Your previous clothing menu is still running. Remove its ensure.
Esc or the ✕ asks "You have unsaved changes"	Expected with Config.ConfirmOnExit (on out of the box): the player changed something free, such as the other sex, a ped of their own or taking something off. Save changes keeps it (free, and the server checks it like any purchase), Discard them leaves as they came in, Keep editing goes back to the menu. false: no question when there is nothing to pay. See Config.ConfirmOnExit.
Save changes is greyed out	The ped being tried on isn't theirs: "The ped you're trying on isn't yours: buy it in Peds to keep it, or discard it." If there's no Save changes at all, the only change is a height previewed in Body: "Only you see it: to keep it, choose it in Body."
A player picked the other sex or a ped, left, and was back as before	It wasn't saved. With Config.ConfirmOnExit, leaving asks first: Save changes or paying keeps it.

Saving and paying

Problem	Why, and what to do
Nothing is charged or saved	The framework wasn't found. The console says framework: none. Start your framework before ZAIDERS Appearance, or set Config.Framework.
Nothing is saved, and the console mentions oxmysql	Add ensure oxmysql before the resource.
ESX: looks aren't saved	The users table has no skin column. Run the ALTER TABLE the console shows.
"Some garments are out of stock: remove them"	An admin is trying on an out-of-stock garment. Remove it from the cart, or put it back in stock with a right click.
A purchase says it's still being saved	The database is slow, often because of a backup. The money only comes back if the save really fails, and the player is told.

Clothes and photos

Problem	Why, and what to do
Garments show a drawing instead of a photo	No photo has been taken for them yet. Take them in the panel. See Catalog photos.
New photos don't show to players	Run ensure zaiders_photos after taking photos.
Catalog photos says the photos resource is missing	Copy zaiders_photos to resources and ensure it before zaiders_appearance.
Some photos came out black or a single color	The game wasn't visible while they were taken (the studio now waits for it, and stops the run after ten minutes of a black picture). Use Delete the broken ones in the panel, or zappearance_clean_photos, then take them again.
A player's clothes look wrong or invisible	/zappearance reloadskin puts the saved clothes on again.
The cart says "Not sold here", or paying says "This store doesn't sell that."	That map shop sells only some things (panel → Shops → Catalog and prices). Also, the clothing store sells clothes and the haircut with its color, never the barber's face, eyes, beard, eyebrows or makeup, and the barber never sells clothes. See What the server checks.
"This store doesn't sell clothes from that pack."	That shop sells only some packs. Buy it at another shop, or add the pack to that shop in the panel.
A clothing store has no Hair	That shop sells only some things, without Hair. Add it in the panel: Shops → Catalog and prices → Sells.
Garments changed after adding or removing a pack	FiveM numbers clothing in start order. Restart the whole server (never a single pack), then join once with an admin. See Clothing IDs & Outfit Shifts.
A garment shows the wrong photo after repacking	With Config.Photos.byContent (on by default), each photo follows its garment by what its files have inside, checked when the server starts, when a pack starts or stops and when you leave the studio. A photo whose garment is now a different one is hidden until you take it again: see Clothing packs → Changes. With byContent = false, take that pack's photos again.
With Config.Photos.url, players see old photos or none	The studio, Changes and photos by content write only on the game server. Upload photos/ to your CDN again after each of them.

Barber shop

Problem	Why, and what to do
The color card shows plain color squares for a haircut	That pack hair's texture can't be read (BC7 or escrowed), its swatches aren't ready yet, the player's game has no WebGL, or Config.Barber.colorCard.enabled = false. The server prepares the packs' hairs in the background after it starts; to start it now, panel → Clothing packs → Hair swatches, or zappearance_hair_swatches in the server console. While a haircut's swatches arrive, the card says "Getting this haircut's swatches ready…".
"This haircut comes with its own color"	The game doesn't tint that haircut, so the color stays as it was and isn't charged. Expected.
The Before | After button is missing	When the barber opened, the menu couldn't read the game's picture (undo and Close-up still work), or Config.Barber.mirror.curtain = false. If it says "The before picture could not be taken.", close the curtain and open it again: the picture is taken each time it opens.
Hold to see the before is greyed out	Nothing has changed yet ("You have not changed anything to compare yet"), or a payment is going on. It's only at the barber shop.
The eyes show as "Eyes 12", or as numbered boxes	A running resource streams an eye pack (mp_eye_colour.ytd), so the game's eye names don't fit: name them in Config.Eyes.names. Numbered boxes without color mean the eyes' picture didn't load, or Config.Eyes.fromGame = false. See Barber shop: eye packs.

Photo studio

Problem	Why, and what to do
Catalog photos says "No invisible head"	zaiders_studio is missing. Copy it to resources (it doesn't go in server.cfg) and restart the server. Until then the head is painted the background's color.
"The invisible head is on the server, but your game joined before it"	Reconnect once.
"To enter the photo studio, get out of the vehicle and have your character standing, not cuffed."	The studio doesn't start from a vehicle, or while your character is dead, downed, cuffed, ragdolled or falling. The panel itself opens anywhere: get out, stand up and start the run again.
F8: "studio: N hairs could not be tinted (…)"	Those hairs were taken at the end on the painted head, with the face removed: their photos are fine. The line says why, for example the hair has parts the game doesn't tint, or its texture couldn't be read (the server couldn't read the names inside its .ytd). See Hair.
F8: "studio: N photos could not be taken: …"	The photos of that run that failed, with each reason and how many. Fix what it says, then run those slots again: Skip the ones that already have a photo takes only what's missing.
A hair keeps its own colors instead of the one picked	The server read that pack hair's model and the game never tints it (no ped_hair_* shader), so players see it like that too. The game's male_heist and female_heist hair 0 are the same.
Beads, ties or other parts of a hair come out in the hair color	The hair's model is encrypted by escrow, so the studio can't tell which parts the game tints and tints the whole hair. A known limit.
Photos at night, in the rain or with changing light, or F8 says another script fights the studio's light	A weather or time script. Add its pause events to Config.Studio.syncPause, or stop it (or make it skip the admin) while you take photos. See Weather and time scripts.
Kicked or banned while taking photos	Your anti-cheat or AFK kick saw an invisible, invincible character standing still high over the sea. Exempt the admin on the server with exports.zaiders_appearance:isInStudio(source) or the zaiders_appearance:studio server event (not the state bag, which a player's game can write): see The photo studio. Or take the photos on a test server without them.
Text, a logo or a counter shows in face or ped photos	Another script draws on the screen. Hide it while you take photos, then take those photos again.
A garment failed as too big for its framing	Give that slot more Distance in Photo framing, then take it again. The rest of the run went on.
The run stopped: "Three photos in a row showed no background…"	Either those garments are bigger than their framing (move that slot's camera back in Photo framing) or the game lost its textures (restart FiveM). Then take them again: the ones that already have a photo are skipped.
The run stopped: "The game's picture came black for over ten minutes…"	The game was minimized or the screen locked for that long. Keep the game on screen and take them again: the ones that already have a photo are skipped.
The run stopped: "The game stopped showing over a minute ago…"	The video memory filled up and the world shows without textures. Restart FiveM and take them again.
Some garments failed on the first run	Their files hadn't downloaded to your game yet (a remote server). Run that slot again: Skip the ones that already have a photo takes only those.
A new clothing pack shows 0 % in Clothing packs and gets no photos	It started after you joined, so your game doesn't have it. Reconnect, then take its photos.
The game crashed or the server restarted during a run	Nothing to do: the next time that character loads, it's put back where it was before entering the studio.

Character creator

Problem	Why, and what to do
It doesn't open for a new character	Your multicharacter fires a different event. Add it to Config.Creator.events.
It doesn't open, and another clothing menu runs	A resource in Config.Creator.skipIfStarted is running, so that one handles new characters.
ESX: esx_skin's menu opens instead	That's expected with esx_skin running (esx_multicharacter needs it). Without a multicharacter, you can stop esx_skin and skinchanger.
The clothing store opened instead of the creator	That character already has a look. The creator is only for new characters.
Esc doesn't leave the creator	A new character leaves by finishing it: Finish character.

Character height

Problem	Why, and what to do
No Height in the creator, no Body tab at the barber's, no Height requests in the panel, and /zappearance requests isn't there	The character height comes off out of the box. Set Config.Height.enabled = true and restart the resource. It's only for the freemode man and woman; creator = false hides it in the creator, and requests.enabled = false removes the requests. See Character height.
"Height is turned off on this server."	Config.Height.enabled = false (out of the box), as above.
"Height change requests are turned off on this server."	Config.Height.requests.enabled = false.
Other players see a character at the game's height	Expected while holding a firearm with combat = 'fair', in a vehicle, in ragdoll or sitting. Otherwise OneSync is off (the console says so once), or a height resource from Config.Height.owners is running.
Characters sink into chairs	Add your emote menu's sitting animations to Config.Height.pause.anims, or call pauseHeight from it. See Sitting emotes.

HUD, shops and tattoos

Problem	Why, and what to do
The server's HUD shows over the menu	Add your HUD to Config.HideHud.resources with its export or event, or use Config.HideHud.custom. See Config reference.
No blips on the map	Config.Shops.blips = false, or the kind's blips are off in the panel's Map blips.
The big map lists the blips under another script's names	Another script uses blip categories 121 to 124. Set Config.Shops.blipLegend to another number, or false.
"Tattoos on this server are handled by another resource."	A resource from Config.Tattoos.owners is running, so the tattoo shop turned itself off.
"The tattoo shop is turned off on this server."	Config.Tattoos.enabled = false.
Other players see my tattoos lighter, or without my addon ones	Check that OneSync is on, not legacy: otherwise the console says so when the server starts. Check Config.Tattoos.sync. While another tattoo resource keeps the tattoos, the others see each one once, without darker layers. ZAIDERS Tattoos stands aside by itself while this menu syncs; another tattoo pack's own sync script that puts tattoos on other players should be turned off. See What other players see.
Other players see the tattoos I try on in another tattoo shop	That shop has no screen with the mouse or scripted camera while trying them on. Its script can call exports.zaiders_appearance:setTattooBusy(true) when it opens and false when it closes. See setTattooBusy.
A pack's tattoos aren't in the shop	The pack must be started, and its fxmanifest.lua must load its overlay files with data_file 'PED_OVERLAY_FILE'. If F8 says the game does not have collection <name>, the pack's overlay file lacks the <nameHash> line after </presets>, which names the collection. ZAIDERS Tattoos 1.0.0 had this problem: update to 1.0.1. See Addon tattoo packs.
"The barber shop is only for freemode characters."	The player is wearing a ped. They can switch to Male or Female in Peds.

Peds

Problem	Why, and what to do
The ped shop is empty	Check Config.PedShop.enabled and the categories in the panel's Peds → Sale. An admin's F8 console has a "ped shop" line saying how many peds it found and why.
A ped is missing from the shop	It's from a newer GTA update than your server's game build, or its category isn't sold.
"Someone else already bought this ped"	One ped, one owner is on, and that ped has its owner.
A ped code doesn't work	It was already redeemed or voided, codes are off (Sale → Redeem codes), or the ped already has its one owner. Codes are typed as they were given, such as M4KQ-2TZB.

Language and config

Problem	Why, and what to do
The console lists config values it fixed	A value in config.lua is missing or written wrong. The menu works anyway. Correct the lines it names. See How the config is checked.
The console says "... no longer exists in this version: it is ignored"	An option a newer version removed, such as Config.Barber.handsOn or Config.Barber.colorCard.matchClothes. Delete that line from config.lua.
Texts show in English though Config.Locale is another language	That language's file is missing or broken. A missing quote or comma breaks the whole file. Check it with a JSON validator.
You changed Config.Locale and some shop names didn't change	Names you wrote yourself are kept. Only the names the game or the panel gave are translated.

Escrow

Problem	Why, and what to do
You lack the required entitlement	The server's license key isn't from the Cfx.re account that bought ZAIDERS Appearance. See Asset Escrow & Clothing.

Still stuck?

Gather the console lines that start with [zaiders_appearance], your framework and its version, and what you did right before the problem. Then open a ticket. Never send license keys or passwords.

If the game crashes with clothing, the cause is usually your clothing packs, not the menu. Start with Crash Diagnosis.