Troubleshooting Guide

Table of Contents

• Installation Issues
• Chat Display Issues
• Command Issues
• Styling Issues
• Proximity Chat Issues
• Job Radio Issues
• Private Message Issues
• Settings Issues
• Performance Issues
• Compatibility Issues
• FAQ

---

Installation Issues

Chat resource not found

Symptom: Error in console: No such export addMessage in resource oxide-chat

Solutions:

1. Ensure the resource is started in server.cfg:

   ensure oxide-chat

2. Check the resource folder name is exactly oxide-chat
3. Ensure it starts after qb-core:

   ensure qb-core
   ensure oxide-chat

4. Run refresh then ensure oxide-chat in console

NUI not loading

Symptom: Chat opens but shows blank/broken UI

Solutions:

1. Clear FiveM cache:

   %localappdata%/FiveM/FiveM.app/data/cache/

   Delete contents of this folder

2. Verify all files exist:

   oxide-chat/
   ├── html/
   │   ├── index.html
   │   ├── css/
   │   │   ├── variables.css
   │   │   ├── animations.css
   │   │   ├── main.css
   │   │   └── settings.css
   │   └── js/
   │       ├── app.js
   │       └── composables/

3. Check F8 console for NUI errors

QBCore not found

Symptom: Error: attempt to index a nil value (global 'QBCore')

Solutions:

1. Ensure qb-core starts first in server.cfg
2. Verify qb-core is working properly
3. Check fxmanifest.lua has qb-core as dependency

Conflicting chat resource

Symptom: Chat displays twice or has weird behavior

Solutions:

1. Remove or disable any other chat resource:

   # Comment out
   # ensure chat
   # ensure esx_chat
   # ensure other-chat

2. Oxide Chat uses provide 'chat' so only one chat should run

---

Chat Display Issues

Chat not appearing

Symptom: Press T but nothing shows

Solutions:

1. Check keybind:

   • Go to FiveM Settings > Key Bindings
   • Look for "Open Chat"
   • Ensure it's bound to T (or your preferred key)

2. Check if chat is enabled:

   -- In F8 or client console
   print(exports['oxide-chat']:isEnabled())

3. Check NUI focus:

   • Another resource may have stolen focus
   • Try pressing Escape multiple times

4. Verify NUI loaded:

   • Check F8 for "NUI ready" or errors

Chat stuck open

Symptom: Can't close chat, mouse trapped

Solutions:

1. Force close via console (F8):

   SetNuiFocus(false, false)

2. Check for script errors in F8 that might prevent close

3. Restart the resource:

   restart oxide-chat

Messages not visible

Symptom: Messages sent but not shown

Solutions:

1. Check chat type visibility:

   • Open settings (/chatsettings)
   • Go to Colors tab
   • Ensure the chat type is visible (eye icon)

2. Check if using correct chatType:

   -- Verify chatType exists in Config.ChatTypes
   print(Config.ChatTypes['yourtype'])

3. Verify color isn't black on dark background:

   • Check the color value in settings

---

Command Issues

Command not working

Symptom: Type command, nothing happens

Solutions:

1. Check syntax:

   /me waves hello       -- Correct
   / me waves hello      -- Wrong (space after /)
   me waves hello        -- Wrong (missing /)

2. Check command exists:

   • Start typing /me and see if suggestion appears
   • If no suggestion, command may not be registered

3. Check cooldown:

   • You may be rate-limited
   • Wait a few seconds and try again

4. Check F8 for errors when executing

Command cooldown too long

Symptom: "Wait X seconds" message too frequently

Solutions:

1. Adjust cooldowns in config:

   Config.Cooldowns = {
       proximity = 1000,  -- Reduce from 1500
       ooc = 3000,        -- Reduce from 5000
   }

2. Check which cooldown type applies:

   • /me, /do, /whisper, /shout use proximity
   • /ooc uses ooc
   • /msg, /reply use pm

Suggestions not showing

Symptom: No autocomplete when typing /

Solutions:

1. Check if command is blacklisted:

   -- config/blacklist.lua
   Config.BlacklistedCommands = { 'yourcommand' }

2. Check ACE permissions:

   • Some commands require permissions
   • Check F8 for permission errors

3. Verify player is loaded:

   • Suggestions refresh after player loads
   • Try /refresh or reconnect

---

Styling Issues

Wrong colors

Symptom: Messages show wrong colors

Solutions:

1. Check config:

   Config.ChatTypes.yourtype = {
       color = '#FF0000',  -- Must be valid hex
   }

2. Check player settings override:

   • Open /chatsettings
   • Go to Colors tab
   • Check if custom color is set

3. Clear settings if corrupted:

   • Delete KVP data
   • Or use Settings > Data > Reset

Styling broken

Symptom: CSS not loading correctly

Solutions:

1. Clear FiveM cache

2. Verify CSS files exist:

   html/css/
   ├── variables.css
   ├── animations.css
   ├── main.css
   └── settings.css

3. Check for CSS syntax errors in F8 console

4. Verify CSS imports in index.html

---

Proximity Chat Issues

Messages not reaching nearby players

Symptom: /me sent but others don't see it

Solutions:

1. Check distance:

   • Default /me range is 15 meters
   • Move closer and retry

2. Check LOS if enabled:

   Config.RequireLOS.me = true  -- May block if can't see

3. Verify on server-side:

   • Check server console for errors
   • Verify GetPlayerCoords returns valid data

LOS blocking messages incorrectly

Symptom: Can see player but message blocked

Solutions:

1. Check if in same vehicle:

   • Vehicle occupants exempt from LOS

2. Disable LOS for that command:

   Config.RequireLOS.me = false

3. Adjust eye-level offset:

   • Default is 0.7m
   • May need adjustment for custom peds

---

Job Radio Issues

"You do not have access to this radio"

Symptom: Job radio command rejected

Solutions:

1. Verify your job:

   -- Check in F8
   local job = QBCore.Functions.GetPlayerData().job
   print(job.name)

2. Check job name matches config:

   -- config/commands.lua
   jobs = { 'police' },  -- Must match exact job name

3. Verify job assignment:

   • Use admin command to set job
   • Check database for correct job

Job messages not received

Symptom: Sent job message but colleagues don't see

Solutions:

1. Verify recipients have same job:

   • Job validation is done twice (client + server)

2. Check for errors in server console

3. Verify player is in GetPlayers list:

   • Player must be fully loaded

---

Private Message Issues

"Player not found"

Symptom: /msg [id] says player not found

Solutions:

1. Verify player ID is correct:

   • Check player list for correct ID
   • IDs are server IDs, not character IDs

2. Player may have disconnected:

   • Target must be online

3. Ensure ID is numeric:

   /msg 5 Hello      -- Correct
   /msg five Hello   -- Wrong

"No one to reply to"

Symptom: /reply says no one to reply to

Solutions:

1. You must receive a PM first:

   • /reply responds to last person who PM'd you

2. Original sender may have disconnected:

   • Reply tracking clears on disconnect

3. Check if cooldown active:

   • Wait a moment and retry

---

Settings Issues

Settings not saving

Symptom: Settings reset on reconnect

Solutions:

1. Check KVP storage:

   • Settings use FiveM KVP system
   • Verify KVP is working on server

2. Check for save errors in F8

3. Try export/import:

   • Export settings in Data tab
   • Reimport after reconnecting

Settings corrupted

Symptom: Chat behaves strangely, settings won't open

Solutions:

1. Reset settings via console:

   DeleteResourceKvp('oxide_chat_settings')

2. Reconnect to server:

   • Default settings will be applied

Import fails

Symptom: Can't import settings from another client

Solutions:

1. Verify import string is complete:

   • Must be valid base64

2. Check version compatibility:

   • Very old exports may need migration

3. Try fresh export from working client

---

Performance Issues

Chat causing FPS drops

Symptom: FPS drops when chat is active

Solutions:

1. Reduce max messages:

   Config.MaxMessages = 50  -- Lower from 100

2. Disable animations:

   • Settings > Appearance > Animations: Off

3. Reduce blur intensity:

   • Settings > Appearance > Blur: 0

Message lag

Symptom: Delay between sending and seeing messages

Solutions:

1. Check network latency:

   • Ping to server affects message timing

2. Check server performance:

   • Server tick rate affects event delivery

3. Reduce message processing:

   • Disable message hooks if not needed

---

Compatibility Issues

Other resources not sending to chat

Symptom: Resource uses chat API but messages don't appear

Solutions:

1. Verify event names:

   -- These should work:
   TriggerEvent('chat:addMessage', {...})
   TriggerClientEvent('chat:addMessage', source, {...})

2. Check export syntax:

   -- Both work:
   exports['chat']:addMessage(...)
   exports['oxide-chat']:addMessage(...)

3. Verify oxide-chat started:

   • Must start before resources that use chat

Chat event fires but nothing shows

Symptom: Event triggers but no message

Solutions:

1. Check message format:

   -- Must have args
   { args = { 'Author', 'Message' } }
   
   -- Not just
   { message = 'Hello' }

2. Check chatEnabled:

   print(exports['oxide-chat']:isEnabled())

---

FAQ

Can I use this alongside another chat?

No. Only one chat resource should run. Oxide Chat uses provide 'chat' to replace the default.

How do I add custom job radios?

See Commands for step-by-step instructions.

Can players change their chat key?

Yes. Go to FiveM Settings > Key Bindings > "Open Chat".

How do I make chat wider/narrower?

Open /chatsettings and adjust Chat Width slider (320-640px).

Why can't I see timestamps?

Check Settings > General > Timestamp Mode. Options: always/hover/never.

How do I hide specific message types?

Open /chatsettings > Colors tab. Toggle visibility per type.

Can I export my settings?

Yes. Open /chatsettings > Data tab > Export. Share the code with others.

Messages disappear too fast?

Increase fade time in Settings > General, or set to 0 for no fade.

---

Getting Help

If your issue isn't covered here:

1. Check F8 console for errors
2. Enable debug mode (Config.Debug = true)
3. Test with /testchat to verify all types work
4. Check for resource conflicts with other NUI resources
5. Verify QBCore is working correctly