Troubleshooting

Common Issues

Issue	Solution
"ox_lib not found"	Ensure ox_lib starts before oxide-multichar in server.cfg
"qb-core not found"	Ensure qb-core starts before oxide-multichar in server.cfg
Black screen on connect	Check for errors in F8 console
No characters showing	Verify database connection and player data
UI not appearing	Ensure web/dist/ exists and contains built files
Cursor not visible	This is handled automatically - report if it persists
Scene not loading	Check scene configuration in config.lua
Character appearance missing	Verify oxide-clothing is installed and working

---

Startup Issues

Resource Not Starting

Symptoms: Resource fails to start, errors in server console.

Solutions:

1. Check resource order in server.cfg:

ensure oxmysql
ensure ox_lib
ensure qb-core
ensure oxide-clothing
ensure oxide-multichar  # Must be after dependencies

2. Verify all dependencies are installed:

   • oxmysql
   • ox_lib
   • qb-core
   • oxide-clothing

3. Check for syntax errors in config.lua:

   • Missing commas
   • Unclosed brackets
   • Invalid Lua syntax

Database Connection Issues

Symptoms: Characters not loading, errors about database queries.

Solutions:

1. Verify oxmysql is configured correctly
2. Check database connection string in server.cfg
3. Ensure players table exists and is accessible
4. Check for database query errors in server console

---

UI Issues

UI Not Appearing

Symptoms: Black screen, no character selection interface.

Solutions:

1. Check if web/dist folder exists:

oxide-multichar/
└── web/
    └── dist/
        ├── index.html
        └── assets/

2. Rebuild the UI if needed:

cd resources/[folder]/oxide-multichar/web
npm install
npm run build

3. Clear FiveM cache:

   • Navigate to %localappdata%/FiveM/FiveM.app/data/cache
   • Delete the cache folder contents
   • Restart FiveM

4. Check F8 console for NUI errors

Cursor Not Appearing

Symptoms: UI is visible but cursor is missing.

Solutions:

1. This should be handled automatically by the resource
2. Check if another resource is interfering with cursor state
3. Try restarting the resource: ensure oxide-multichar

---

Character Issues

Characters Not Displaying

Symptoms: Character cards are empty or not showing.

Solutions:

1. Check database for character data
2. Verify player license matches database records
3. Check server console for query errors
4. Ensure oxide-clothing exports are working

Character Appearance Not Loading

Symptoms: Preview peds show default appearance instead of saved outfits.

Solutions:

1. Verify oxide-clothing is installed and started
2. Check that player_outfits table exists in database
3. Test oxide-clothing independently
4. Check for errors in F8 console related to appearance

Cannot Create New Character

Symptoms: Create button not working, errors during creation.

Solutions:

1. Check if character slot limit is reached
2. Verify form validation is passing
3. Check server console for creation errors
4. Ensure all required fields are filled

---

Scene Issues

Scene Not Loading

Symptoms: Black background, no scene environment.

Solutions:

1. Check scene configuration in config.lua:

Config.Scenes = {
    default = 'apartment',  -- Must match a scene in list
    list = {
        apartment = { ... }
    }
}

2. Verify scene coordinates are valid
3. Check if interior is loaded (some scenes require interiors)
4. Test with a different scene to isolate the issue

Camera Issues

Symptoms: Camera stuck, wrong angle, not transitioning.

Solutions:

1. Verify camera coordinates in scene config
2. Check rotation values (pitch, roll, yaw)
3. Ensure FOV is a reasonable value (30-90)
4. Check for conflicting camera scripts

Weather/Time Not Working

Symptoms: Scene uses server weather instead of configured override.

Solutions:

1. Verify weather string is valid:

   • EXTRASUNNY, CLEAR, FOGGY, etc.

2. Check time format:

time = { hour = 20, minute = 0 }  -- 24-hour format

---

Performance Issues

Slow Loading

Symptoms: Long load times, stuttering during scene transitions.

Solutions:

1. Reduce number of ped positions per scene
2. Use simpler vehicle models
3. Check for memory leaks in other resources
4. Verify database query performance

Memory Usage

Symptoms: High memory usage, crashes.

Solutions:

1. Ensure peds and vehicles are properly deleted on scene change
2. Check for entity leaks
3. Monitor resource memory usage

---

Spawn Issues

Spawning at Wrong Location

Symptoms: Character spawns at unexpected coordinates.

Solutions:

1. Check DefaultSpawn configuration:

Config.DefaultSpawn = vector4(-1035.71, -2731.87, 12.86, 0.0)

2. Verify qb-spawn/qb-apartments are configured correctly
3. Check SkipSelection setting

Spawn Selection Not Opening

Symptoms: Direct spawn instead of qb-spawn selection.

Solutions:

1. Ensure qb-spawn is installed and started
2. Check Config.SkipSelection is false
3. Verify qb-spawn is compatible with your QBCore version

---

Logout Issues

Logout Command Not Working

Symptoms: /logout command does nothing.

Solutions:

1. Check logout is enabled:

Config.Logout = {
    enabled = true,
    command = 'logout',
    ...
}

2. Verify command name matches what you're typing
3. Check for command conflicts with other resources

Logout Transition Issues

Symptoms: Screen freeze during logout, no fade effect.

Solutions:

1. Check fade duration values are reasonable:

fadeOutDuration = 500,   -- milliseconds
holdDuration = 1500,
fadeInDuration = 500,

2. Verify NUI is responding
3. Check for errors during logout process

---

Getting Help

If you're still experiencing issues:

1. Check the F8 console for client-side errors

2. Check server console for server-side errors

3. Enable debug mode if available

4. Collect the following information:

   • Server console errors
   • Client console errors (F8)
   • Steps to reproduce the issue
   • Your config.lua (remove sensitive data)
   • FiveM server version
   • QBCore version

5. Open a support ticket with the above information