Troubleshooting

Start here. Run mcdiag in the server console. It names the framework, clothing, housing and tattoo resources it resolved, the database, the Discord and store wiring, and every problem it found in your config.lua — which answers most of what follows before you read it.

Startup and framework

Nobody can connect, and the console repeats a boxed “WRONG RESOURCE FOLDER NAME” error

The folder is not named nuggs_multicharacter. The banner names what it found and what it needs. Stop the server, rename the folder, make sure server.cfg says ensure nuggs_multicharacter, start again — nothing else changes. Almost always this is a suffix an unzip added by itself: -main, -master, (1), a version number. A bracketed parent directory such as [qbx] is fine and is not part of the name. See The folder name is locked.

Framework detected as none

Your framework starts after this resource. Move ensure nuggs_multicharacter below it in server.cfg. If you renamed your core resource, set Config.Framework explicitly.

Detected as qbcore on a Qbox server

qb-core is still running alongside qbx_core. Set Config.Framework = "qbox".

Character screen never appears

Check the banner. database NOT CONNECTED means oxmysql is not up; framework NONE DETECTED is the entry above.

Qbox: User does not exist on login

qbx_core’s connection deferral has not finished. Ensure this resource after qbx_core.

Config edits do nothing, or Config.Framework is ignored

config.lua was moved below shared/framework.lua in fxmanifest.lua. Put it back above.

Console warns the config is an old version

A release added options. Diff your config.lua against config.lua.example and read CHANGELOG.md.

You lack the required entitlement

The server key is not on the account that bought the resource. Add it in Keymaster.

Script error on line 1 of a file that looks fine

The .fxap or a .lua was corrupted by an FTP client in ASCII mode. Re-upload in binary mode, or use SFTP.

Nothing at all in the console

Turn on Config.Debug and restart. Two character screens fighting over one ped raises no Lua error on its own, which is why the trace exists.

Two screens, or the creator running twice

Two character screens at once, or they fight over the ped

You did not stop the one you are replacing. ESX: stop esx_multicharacter. QBCore: stop qb-multicharacter. Qbox: set characters.useExternalCharacters = true in qbx_core/config/client.lua, and startingApartment = false in the same block.

Note that ensure [core] starts every folder inside [core], so move the old resource somewhere nothing ensures; renaming it is not enough. The console prints an explicit error naming the rival resource.

ESX: the old esx_identity form appears instead of the creator

Config.Multichar in es_extended/shared/config/main.lua is false, so ESX dropped to single-character mode. That line must name this resource — see Install in README.md.

Character creator opens twice

Something fires qb-clothes:client:CreateFirstCharacter at illenium-appearance after this resource made the character, and illenium has no config option for it. Fix in this order:

1. Qbox — startingApartment = false and useExternalCharacters = true in qbx_core/config/client.lua, then a full server restart.
2. QBCore — park qb-multicharacter and qb-apartments.
3. Run grep -rn "CreateFirstCharacter" resources/ and account for every hit.

See QBCore and Qbox: turn off the other creator in README.md.

Clothing and tattoos

Clothing and tattoos are not saved, or are wiped after spawn

Same cause as the entry above: illenium’s SetInitialClothes strips the ped and its saveAppearance deletes the playerskins row this resource wrote. Compare multicharacter_characters.tattoos against playerskins.skin for that citizenid to confirm, then stop the trigger.

Tattoos are in multicharacter_characters but playerskins shows "tattoos":[]

A shop, barber or outfit change saved over them from an empty in-memory tattoo cache. The list is handed over on every spawn and both copies are reconciled at login — run /mctattoos <player> to repair a character already hit.

New characters have no clothes in shops

Your clothing resource was not recognised. Check the appearance line on the banner: if it names your resource, set Config.Appearance.publish to "illenium" or "qbclothing" explicitly; if it says none detected, describe it in Config.Appearance.custom.

A new character spawns in default clothes, and the first shop saves those over them

The clothing resource keeps its appearance in its own tables and was never handed the character. Built-in adapters cover bl_appearance, rcore_clothing, tgiann-clothing and crm-appearance; anything else needs a Config.Appearance.custom entry — start with readPed and saveSelf.

The banner names the wrong clothing resource

Two are running. Name the one that owns the ped with Config.Appearance.resource.

Clothing resource errors on load

The wrong playerskins format was written. Set Config.Appearance.publish explicitly — illenium’s shape and qb-clothing’s are not interchangeable.

Tattoos vanish after a haircut

Something on your server is writing the appearance blob without preserving the tattoo column. Tattoos live in users.tattoos / multicharacter_characters.tattoos, not in the skin.

A tattoo draws nothing

The collection or overlay name does not exist in this game build. Check it with /cctattoo <collection> <overlay> — an unknown name raises no error, it just draws nothing.

Arrival points and housing

No home card on the arrival rail

The banner’s housing line says what was found. none detected means either nothing is running or its table has not been created yet — run that resource’s own SQL. A character who owns nothing gets no card, which is correct.

Home card appears but the player lands outside

Either the housing script has no cross-resource entry point (esx_property is the one that does not, by design) or it was still loading. Raise Config.Housing.enterDelay.

Home card appears for a property that was sold

Ownership is read from the housing script’s own table at login. If the row still names this character, that script did not clear it on sale.

A housing or motel script this resource has never heard of

Config.Housing.custom. Naming its table, owner and key is usually the whole integration.

Scene, camera and backdrop

A line-up pose does not play

The anim dict is missing from this game build. Run /ccpose — it lists every configured pose and marks the missing ones.

Camera frames empty ground

Your Config.Scene coordinates and the ped position disagree. Run /ccdebug in the creator, and /ccpos where you want the shot.

Backdrop covers the characters

Config.Scene.backdrop.distance is too small, so the panel draws in front of the peds. Raise it.

Backdrop image does not load

The file is not in files{} in fxmanifest.lua. Anything under html/images/ already is; anywhere else needs a line adding.

Membership, store and Discord

Slots granted but the player still sees the old number

They were already in the world, and slots take effect on their next relog. Use RefreshCharacterScreen(source) for a player still on the character screen.

Tebex delivery grants twice

You left {transaction} off the command. The reference column is what makes a retried delivery pay out once.

Store prices do not match the webstore

Config.Store.tebex.enabled is off, so the numbers in config.lua are used as written. Turn it on, set nuggs_tebex_secret in server.cfg, and run mcperks tebex to see what the store answered.

One package keeps the config price

Its tebexId is not a package on your store. mcperks tebex names the mismatches.

Discord roles ignored

Five possible causes, and mcperks discord <playerId> reports all of them: nuggs_discord_token / nuggs_discord_server unset, the bot is not in your guild, the Server Members Intent is off in the developer portal, no role is mapped to a tier, or the player is not running Discord.

Discord roles work, then stop for a few minutes

A rate limit. The lookup backs off for exactly as long as Discord asks, and an inconclusive answer is never cached, so nobody is demoted while it waits.

mcperks says “denied” in game

It needs a framework admin or add_ace <group> command.mcperks allow. The console is always allowed.

---

Still stuck? Open a ticket and paste the output of mcdiag.