# Troubleshoot multicharacter loading

A black screen is an observation, not a diagnosis. First determine the **last completed stage**. A shared-item syntax error, a missing database table and a failed spawn callback can all leave the player looking at a similar screen.

This guide follows `qb-multicharacter` at `85a03c4f` and core at `9b3cddcc`. Third-party selectors, appearance systems and inventory forks need their own integration mapping. The checks are source-reviewed; no live FiveM execution is claimed.

## Evidence to collect

Record the first error after a clean startup, then the first F8/NUI error during one reproduction. Include file and line, active txAdmin profile, deployed resource commits, recent changes, and whether the failure affects a new character, an existing character or every player. Keep license identifiers, connection strings and character JSON out of public reports.

## Safe diagnostic

### Choose the correct branch

| Last visible stage | Inspect next | Expected evidence |
| --- | --- | --- |
| Loading screen never reaches character selection | First core/database/selector startup error, loading-screen shutdown and selector UI assets | Dependencies started; selector's client code reached the menu-opening path |
| Menu opens but characters do not populate | NUI `setupCharacters`, server callback of the same purpose, SQL query/JSON decode | Callback completes and the UI receives an array, including an empty array for no characters |
| Character can be selected, then black screen | NUI `selectCharacter` → `loadUserData` → login/preload → housing/spawn branch | Identify exactly which callback/event does not finish |
| Only new characters fail | `createCharacter`, starter items, `Apartments.Starting`, appearance setup | New-character initialization completes without inventory/shared-item errors |
| Only an existing character fails | Its saved position/metadata/appearance and last-location branch | A minimized test copy isolates the bad field or missing integration |
| Started after installing another script | Changed shared files and the first dependency error | Core initializes before downstream resources read its tables |

Use F8 for client errors and the server console for server errors. NUI callbacks are a third context; a successful HTTP reply to a selector callback does not prove the subsequent server login or spawn succeeded.

### Follow the actual source sequence

In the pinned client, `setupCharacters` calls `qb-multicharacter:server:setupCharacters`; the server reads `players` by license and decodes character fields. `selectCharacter` sends `qb-multicharacter:server:loadUserData` with the selected character data.

The pinned server then calls `QBCore.Player.Login`, waits for its preload flag, runs `loadHouseData`, and chooses a spawn branch. `loadHouseData` reads `houselocations`, even though the next step may use a different spawn UI. A missing housing table can therefore interrupt the sequence before the spawn selector opens.

Do not create a guessed `houselocations` table. Confirm whether your configured stack includes the owning housing resource and its matching schema, or whether your custom selector integration should intentionally bypass that step. See [oxmysql schema diagnostics](/docs/troubleshooting/oxmysql#schema-errors-are-not-connection-errors).

For temporary instrumentation, put short stage markers immediately before and after the suspected call **on staging**. For example, log that login was entered, login succeeded, preloading completed and house data returned. Do not log the whole character payload. Remove the temporary logging after identifying the failed stage.

### Existing-character versus new-character paths

The pinned new-character handler can enter an apartment setup branch and grants starter items through `qb-inventory:AddItem`. An undefined starter item belongs in shared-item/inventory diagnostics, not a UI reset.

With `Config.SkipSelection`, inspect `spawnLastLocation` specifically: the pinned client requests `apartments:GetOwnedApartment` and performs its spawn work inside `if result then`. Verify that this callback exists and returns the expected result for your installation. Do not assume enabling “skip selection” removes all apartment dependencies, and do not bypass ownership or login checks to force a fade-in.

## Fix

### Source-specific closeUI callback defect

At `85a03c4f`, `client.lua` registers `closeUI` with a parameter named `_` but the next line reads `data.cData`. That callback therefore does not use the supplied payload correctly. **This is specific to the `closeUI` path**; `selectCharacter` already declares `data` and is a separate callback.

If your NUI actually invokes `closeUI` and the stack trace points to that access, compare with an upstream correction or make this narrowly scoped change in your staging branch:

```diff
-RegisterNUICallback('closeUI', function(_, cb)
+RegisterNUICallback('closeUI', function(data, cb)
+    if type(data) ~= 'table' or type(data.cData) ~= 'table' then
+        cb({ ok = false, error = 'missing-character-data' })
+        return
+    end
     local cData = data.cData
```

Keep the remainder of the handler and its existing successful `cb` response; ensure the NUI caller handles the new error response. This repairs the parameter handling, not every possible failure later in the character flow. The server must still validate the selected character and player identity. Retest cancel, selection and reconnect paths after any selector patch.

### Worked case: black screen after installing a script

A Cfx.re user reported a black screen after adding a mechanic script on **25 January 2026**, including `attempt to index a nil value (field 'items')`. A reply on **13 February 2026** suggested checking the item additions in `qb-core/shared/items.lua`. The thread is evidence of the symptom and suggested investigation, not a tested universal repair.

Use this reproducible diagnostic sequence for the same class of failure:

1. Reproduce from a clean staging start and preserve the first startup error. Do not begin with the mechanic script's later nil error.
2. Compare the changed shared item file with the last working copy: `git diff -- shared/items.lua` from the core directory. Check missing commas/braces, duplicate keys, casing and whether entries were inserted inside the correct table.
3. Disable the newly added custom resource in staging and restore only its related shared-file edits from your reviewed backup. A copy of the current changes must be retained for correction; do not discard unrelated customization.
4. Restart the staging server as a coordinated resource set. Confirm that core, inventory and character selection now initialize.
5. Reapply one corrected item and then the custom script. Confirm the item's schema and use behavior with the [usable-item guide](/docs/guides/item-use-effect).
6. Test a new and an existing character, then reconnect. Compare the result with the baseline before restoring other changes.

Expected evidence is a clean first startup and a completed character flow, not simply hiding the final error. If core started successfully throughout, inspect the exact expression on the mechanic script's failing line: `items`, `Items` and `PlayerData.items` are not interchangeable paths. Do not manufacture a global table just to make a nil error stop.

### UI and data repairs need different rollback plans

For a failed NUI asset, fix the manifest/file path or JavaScript error. For a callback mismatch, align the actual caller and handler. For an invalid saved JSON field, inspect one backed-up record with the owning resource's schema and recovery process. Do not delete all characters or force `LocalPlayer.state.isLoggedIn = true` as a workaround.

## Manual acceptance checks

| Scenario | Required result |
| --- | --- |
| Existing character | Selection → correct spawn → controllable/visible player |
| New character | Creation → appearance/apartment flow as configured → starter items once |
| Empty character list | UI remains usable and allows authorized creation |
| Cancel/back/logout | Focus, preview ped and camera are cleaned up |
| Reconnect | Saved character state loads without duplicating initialization |
| Changed spawn/appearance resource | Its callback contract matches the selector and no old handler competes |
| Invalid or unauthorized character request | Server refuses it without granting another character's state |

Perform deletion checks only on a disposable staging character, never on an existing production record as a diagnostic shortcut.

## Rollback

Restore the previously working selector/core/spawn/appearance/inventory combination and reviewed local configuration. A UI-only rollback should not overwrite character records. Restore database state only when a migration or data repair changed it, with a plan for legitimate writes since the backup. Reconfirm both new and existing character flows after recovery.

## Sources

- [Selector client, 85a03c4f](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/client.lua): NUI callbacks and last-location path.
- [Selector server, 85a03c4f](https://github.com/qbcore-fivem/qb-multicharacter/blob/85a03c4f3bdc100e898b9fb65614a9ce914fe926/server.lua): login, preload, housing and starter items.
- [Core player implementation, 9b3cddcc](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/server/player.lua).
- [Cfx.re mechanic-script loading report](https://forum.cfx.re/t/help/5379790): report and follow-up dates distinguished above.
- [NUI callbacks](https://docs.fivem.net/docs/scripting-manual/nui-development/nui-callbacks/) and [resource load order](/docs/troubleshooting/resource-load-order).
