> ## Documentation Index
> Fetch the complete documentation index at: https://docs.awokenlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and how to fix them.

## Resource fails to start - name assertion error

The folder must be named exactly **`awoken_multicharacter`** (underscore) for all frameworks. No version
numbers, no suffixes, no extra characters. The resource checks its own name on startup and
refuses to load if it doesn't match.

***

## Players spawn into the world instead of hitting the selector

<Tabs>
  <Tab title="QBX / QBCore">
    1. **The old multichar is still running.** Search every `.cfg` file on your server, not
       just `server.cfg`. A resource ensured in a category file will still load even if you
       commented it out in the main config.
    2. **QBX's built-in flag isn't disabled.** In `qbx_core/config/client.lua`, confirm
       `multicharacter = false` is set.
  </Tab>

  <Tab title="ESX">
    1. **`Config.Multichar` is not `true`.** Open `es_extended/config.lua` and confirm
       `Config.Multichar = true`. Without it ESX spawns the player immediately, bypassing
       the selector entirely.
    2. **`esx_multicharacter` is still running.** Check every `.cfg` file on your server.
       A resource ensured in a category file will still load even if you commented it out
       in the main config.
  </Tab>
</Tabs>

***

## Character creation fails

<Tabs>
  <Tab title="QBX / QBCore">
    Check the server console for the exact error. The most common cause is a `qbx_core` version
    that is too old or a missing `players` table column. Make sure you are on a recent release of
    `qbx_core` and that your DB schema is up to date.
  </Tab>

  <Tab title="ESX">
    **`Field 'ssn' doesn't have a default value`** (or any other NOT NULL column error)

    The resource does not INSERT into `users` directly. It fires `esx:onPlayerJoined` and lets
    ESX handle row creation. If you see this error:

    * Confirm `Config.Multichar = true` is set in `es_extended/config.lua`
    * Check that no other resource is hooking into the join flow and causing a conflict
    * Check that `es_extended` is starting cleanly before `awoken_multicharacter`
  </Tab>
</Tabs>

***

## Clothing editor doesn't open for new characters

<Tabs>
  <Tab title="QBX / QBCore">
    The clothing editor is opened by firing `Config.FirstCharacterEvent` on the client. If it
    isn't showing:

    * Make sure the event name matches what your appearance resource expects. See the
      [Configuration](/configuration) page for the correct event per resource.
    * Confirm the appearance resource is actually running (`GetResourceState` in F8 console).
    * This only fires when `Config.StartingApartment = false`. If apartments is enabled,
      the apartment resource is responsible for opening the editor.
  </Tab>

  <Tab title="ESX">
    The editor that opens depends on `Config.AppearanceResource`:

    * `illenium-appearance`: fires `esx_skin:openSaveableMenu`
    * `fivem-appearance`: fires `fivem-appearance:openMenu`
    * `ox_appearance`: fires `Config.FirstCharacterEvent`
    * Any other value / blank: fires `esx_skin:openSaveableMenu` if `esx_skin` is running,
      otherwise fires `Config.FirstCharacterEvent`

    If nothing opens, check that the relevant resource is started and check the F8 console
    for errors around the time the new character spawns.

    If `Config.StartingApartment = true`, the apartment resource handles the UI - make sure
    your housing resource is in the supported list (see [Configuration](/configuration)).
  </Tab>
</Tabs>

***

## Preview ped shows default appearance (saved skin not loading)

The preview ped in the selector should show the character's last saved appearance. If it shows
a blank freemode model instead:

* **Skin was never saved.** If the player closed the clothing editor without saving, there is
  nothing to load. Once they save an appearance it will display correctly.
* **Appearance resource not running.** Without it the skin application path won't execute.

<Tabs>
  <Tab title="QBX / QBCore">
    Skins are read from the `playerskins` table (`citizenid`, `model`, `skin` columns).
    Check that this table exists and that your appearance resource is actually writing to it
    when players save their look.
  </Tab>

  <Tab title="ESX">
    Skins are read from the `skin` column on the `users` table. Check that the column exists
    and contains data for the character in question.

    If the column has data but the preview still shows default, check the server console for
    skin-related log lines when the character select screen opens. If nothing is logged, the
    skin data is not making it from the server to the client.
  </Tab>
</Tabs>

***

## Two apartment / skin screens overlap on new characters (or the ped is invisible)

This means **two resources are both running a new-player spawn flow** - awoken and your
framework/housing script. They fire at the same time and fight for focus, so you get the
character selector or clothing editor stacked over the apartment selector, and the ped can end
up invisible during customisation.

Fix it by making **one** resource own the flow:

<Tabs>
  <Tab title="QBX / QBCore">
    Using `qbx_properties` (or any qbx apartment script):

    1. In `qbx_core/config/client.lua` set `startingApartment = false` so qbx stops running its
       own starter apartment.
    2. In awoken `config.lua` set `Config.StartingApartment = true`.

    Also confirm `useExternalCharacters = true` is set in `qbx_core/config/client.lua`.
  </Tab>

  <Tab title="ESX">
    Either let your apartment script own it (`Config.StartingApartment = true` and disable any
    built-in starter-apartment auto-spawn), or let awoken own it (`Config.StartingApartment = false`)
    and make sure no housing script auto-spawns new players on load.
  </Tab>
</Tabs>

See the [Starting apartment](/resources/awoken-multicharacter/configuration#starting-apartment)
section for the full single-owner rule.

***

## Apartment selector doesn't open for new characters

Check the server console when a new character is created. The resource logs which apartment
resources it detected so you can see exactly what it found.

<Tabs>
  <Tab title="QBX / QBCore">
    Supported: `ps-housing`, `qbx_properties`, `qbx_apartments`, `qb-apartments`,
    `bcs_housing`, `0r-apartment`, `okokSpawnSelector`, `vms_spawnselector`

    If yours isn't listed, set `Config.StartingApartment = false` and use
    `Config.NewPlayerNoApartmentStartCoords` as the fallback spawn point.
  </Tab>

  <Tab title="ESX">
    Supported: `esx_property`, `ps-housing`, `esx_apartments`, `es_apartments`,
    `bcs_housing`, `okokSpawnSelector`, `vms_spawnselector`, `luxart-apartment`

    If yours isn't listed, set `Config.StartingApartment = false` and use
    `Config.NewPlayerNoApartmentStartCoords` as the fallback spawn point.
  </Tab>
</Tabs>

***

## Discord role slots aren't working

* **Bot token wrong or expired.** Regenerate it in the Discord Developer Portal.
* **Server Members Intent disabled.** Go to the Developer Portal, open your app, go to Bot,
  then Privileged Gateway Intents, and enable Server Members Intent. Without it role fetches
  silently fail and everyone gets `Config.DefaultSlots`.
* **Wrong IDs.** `guildId` is your Discord server ID, not a channel or role ID. Right-click
  your server icon and copy the Server ID (requires Developer Mode in Discord settings).
  For role IDs, right-click the role and copy the Role ID.

Role data is cached when the player connects. A reconnect is needed for updated slots to take effect.

***

## Framework preload times out (character loads but some systems don't initialise)

The resource waits up to 10 seconds for the framework's player loaded event after character
selection. If it times out the character still spawns, but ESX or QBX dependent resources may
not have their player object ready in time.

<Tabs>
  <Tab title="QBX / QBCore">
    The gate listens for `QBCore:Server:PlayerLoaded`. If that event isn't firing, check
    that nothing is blocking `qbx_core` or `qb-core`'s player load sequence.
  </Tab>

  <Tab title="ESX">
    The gate listens for `esx:playerLoaded` server-side. If it isn't firing, check that
    `es_extended` is healthy and that no resource is preventing `esx:onPlayerJoined` from
    completing normally.
  </Tab>
</Tabs>