Troubleshooting#

The old ESX character menu shows up, or characters cannot be selected#

Two character menus are running at once. Remove ensure esx_multicharacter and ensure esx_identity (or qb-multicharacter) from server.cfg. Koja Multicharacter also stops them when they start and prints:

[KOJA-MULTICHARACTER] stopped esx_multicharacter, koja-multicharacter replaces it

If you see this line, another resource is starting the old menu. Find which one starts it and remove that call.

Characters do not load on ESX#

The console shows:

[KOJA-MULTICHARACTER] es_extended runs with Config.Multichar = false ...

Set Config.Multichar = true in es_extended/shared/config/main.lua, or keep the esx_multicharacter folder in resources without ensuring it. See Installation.

No supported framework found#

The console shows No supported framework found (es_extended, qb-core, qbx_core). Start Koja Multicharacter after your framework and koja-lib in server.cfg.

QBX still opens its own character menu#

Set characters.useExternalCharacters = true in qbx_core/config/client.lua and restart the server.

The koja-spawnselector map does not open#

• Check that Config.Spawn.UseKojaSpawnSelector is true.
• Start koja-spawnselector before koja-multicharacter.
• With Config.Debug = true the console prints koja-spawnselector integration attached when the link works, or koja-spawnselector integration failed: ... with the reason.

A spawn point is missing#

The console prints spawn "<id>" skipped: <reason> when a spawn from shared/spawns.lua or RegisterSpawn is invalid. Fix the field it names.

A character clips through walls when switching#

The scene location is too tight for the walk-in. Lower Config.Scene.Transition.WalkDistance, pick another location, or set Transition.Enabled = false for an instant swap.

A hook throws an error#

[KOJA-MULTICHARACTER] hook beforeSpawn from my-resource failed: ...

The error is in the named resource. The action continues as if the hook returned nothing.