Troubleshooting

The game crashes on the selector (streaming / .ymt)

Servers with heavy custom clothing can hit the game's .ymt streaming limit when the selector repeatedly requests the freemode ped models. The script pre-streams mp_m_freemode_01 and mp_f_freemode_01 on open to avoid this. Keep it enabled:

crashPreventionForYmtLimits = true,

Only set this false if you are specifically profiling streaming memory.

A character had a broken model / crashed on load

If a saved ped model is corrupt or uninstalled (e.g. a stale hash like 991402986), the real character load — read straight from the DB by your appearance resource — would crash. The selector guards against this: because a character is always previewed before it can be entered, the bad model value is auto-repaired in the DB at preview time, so the later load is safe. No action needed; the fix is automatic.

No music plays

• xsound isn't started. Audio requires xsound. Without it, search, selection and the lyrics UI still work — there's just no sound. Add ensure xsound before the selector. The console prints a one-line notice when xsound is missing.
• The demo YouTube key is rate-limited. If song search returns nothing, the shipped demo key is likely rate-limited or revoked. Replace music.youtubeApiKey in settings/options.lua with your own YouTube Data API v3 key.
• music.enabled = false. Confirm the feature is on.

Lyrics don't show

Audio can play without lyrics if none are found for that title. The lookup is best-effort and cached. Titles with heavy noise or very obscure tracks may not resolve; the audio still plays and only the lyric layer stays hidden. Diacritic-heavy titles are ASCII-folded automatically, so that is not the cause.

Tebex slots aren't importing

• Set tebexShopImport = true in settings/options.lua.
• Provide the secret: set sv_tebexSecret "..." in server.cfg. If it's missing, the Tebex module logs sv_tebexSecret convar is not set and disables itself.
• Do not rename the addNewCharacterSlot command — the Tebex package feeds transactions through it.
• Redemptions are rate-limited (5 attempts / 60s) and each tbx- transaction can be claimed once.

Text is in the wrong language

Set the locale explicitly in server.cfg:

setr ox:locale "en"

Use a shipped code (see Localization). Missing strings fall back to English.

A partner isn't appearing beside the character

• The bond must have been accepted. Pending invites expire after 10 minutes.
• An invite is only delivered while the target views that character on the selector — the accepter must open the selector on the invited character to see and accept the toast.
• Invites are held in memory and are lost on a resource restart; re-send after restarting.
• Confirm partnerInvite = true in settings/options.lua.
• Remember there is no /partnerinvite command — invites come from the selector menu; admins can force a pairing with /forcepartner.

Two selectors / conflicts

BUPA Multicharacter provides qb-multicharacter. Make sure no other multicharacter resource is running alongside it, and that it starts after ox_lib, oxmysql and your framework.