FAQ & Troubleshooting

Common questions and solutions.

Installation Issues

"Chat Theme not loading"

Problem: Chat shows errors or default styling

Solutions:

1. Check server.cfg load order:

   ensure chat
   ensure of_chat_theme

   ✓ chat MUST come before of_chat_theme

2. Verify ox_lib is installed:

   ensure ox_lib
   ensure chat
   ensure of_chat_theme

3. Check console for errors:

   [of_chat_theme] Error: ...

"Framework not detected"

Problem: Commands show "(unknown)" for player names

Solution:

1. Ensure your framework is started:

   ensure qb-core  # or es_extended / qbx_core
   ensure ox_lib
   ensure chat
   ensure of_chat_theme

2. Check Config.Framework matches your framework:

   Config.Framework = "qb"  -- "qb" | "esx"

3. Verify framework exports are available:

   • Framework.Functions.GetPlayerData()
   • Framework.Functions.GetPlayerName()

Command Issues

"/me command not working"

Problem: Command doesn't execute

Checks:

1. Is it enabled in config?

   Config.Commands.me.enabled = true

2. Are you loaded into the server?

   • Use /clearchat to test
   • Check framework loaded: /me loaded should work

3. Is chat open?

   • Press T to open chat
   • Type /me test

4. Check console for errors

Template Issues

"Messages look all the same"

Problem: Templates not applying

Solutions:

1. Check config/templates.lua for syntax errors:

   Config.Theme = {
       ['cmd:me'] = T.build()  -- Missing closing parenthesis?
           :tag('ME')
           :done()
   }

2. Verify template ID matches command:

   Config.Commands.me.colors = getTemplate("me")  -- Must exist

3. Check for Lua syntax errors:

   • Use Lua linter
   • Restart server to see errors

4. Test template directly:

   TriggerEvent('chat:addMessage', {
       templateId = 'cmd:me',
       args = { "TestName", "Test message" }
   })

"Placeholders not replacing"

Problem: Shows {Framework:GetName} instead of player name

Causes:

1. Framework not loaded
2. Placeholder doesn't exist
3. Server-side template (use dont_register:)
4. Syntax error in placeholder

Solutions:

-- Verify placeholder exists
Client.Custom["Placeholder"]["GetName"] = function()
    return Framework.Functions.GetPlayerName()
end

-- Use in template
T.text('{Placeholder:GetName}')

"3D bubbles not showing"

Problem: /me actions don't appear above head

Solution:

1. Enable bubble module:

   Config.Modules.bubble = true

2. Check bubble range:

   Config.Bubble = {
       range = 15.0,  -- Can you see the player?
   }

3. Verify line-of-sight:

   Config.Commands.me.los = false  -- Try disabling

Channel Issues

"Players can't write to channel"

Problem: Access denied or command not working

Checks:

1. User has permission:

   participants = {
       write = { { type = 'job', value = 'police' } }  -- User is police?
   }

2. Channel exists:

   Config.Channels = {
       { id = 'police', ... }
   }

3. Command is assigned:

   Config.Commands.msg.channel = 'police'

"Channel selector not showing"

Problem: Can't switch channels in UI

Solution:

1. Ensure multiple channels configured:

   Config.Channels = {
       { id = 'all', ... },
       { id = 'twitter', ... },  -- At least 2 channels
   }

2. UI must be enabled and have permission

3. Check UI settings not disabled

Framework Integration

"ESX players see generic names"

Problem: Shows "Unknown" instead of character name

Solution:

1. Verify ESX is loaded before chat:

   ensure es_extended
   ensure ox_lib
   ensure chat
   ensure of_chat_theme

2. Set correct framework:

   Config.Framework = "esx"

3. Check ESX player data available:

   • Verify ESX callback working
   • Test: TriggerServerEvent('esx:getPlayerData')

"QB Jobs not showing"

Problem: /msg shows player ID instead of job

Solution:

1. Ensure QB is loaded
2. Verify placeholder syntax:

   {Framework:GetJob}      -- QB format
   {Framework.Functions.GetPlayerData().job.name}  -- Alternative

Logging Issues

"Messages not logging to Discord"

Problem: Webhook not receiving messages

Checks:

1. Webhook URL configured:

   Config.Webhooks = {
       ["chat"] = "https://discord.com/api/webhooks/123/abc"
   }

2. Webhook is valid and not expired

3. Message type is loggable:

   • /me logs
   • /ooc logs
   • Custom commands may not log

4. Check Discord permissions

Mobile / Phone Integration

"Phone messages not syncing"

Problem: LB-PHONE posts don't appear in chat

Solution:

1. Enable hook:

   Config.Hooks = {
       ["LB-PHONE"] = {
           birdy = true
       }
   }

2. Restart server

3. LB-PHONE must be running before of_chat_theme

Customization Help

"How do I change ALL message colors?"

Edit theme colors in template:

Config.Theme['cmd:me'] = T.build()
    :bg('#0a0e27')  -- Dark background
    :message({ color = '#00ff00' })  -- Green text
    :done()

"How do I add a custom command?"

Create in config/commands/client.lua:

Commands.client("greet", {
    handler = function(ctx)
        Commands.sendProximity('cmd:me', {
            ctx.author,
            "waves hello"
        }, 15.0)
    end,
})

"How do I hide a command from suggestions?"

Set command = false or don't register:

Config.Commands.custom = {
    enabled = true,
    command = false,  -- Hidden
}

Getting Help

If your issue isn't listed:

1. Check console for error messages
2. Enable debug mode:

   Config.Debug = true

3. Check resource dependencies are all loaded
4. Verify file permissions in resource folder
5. Try with minimal config (default values)

Report a Bug

Include:

• Error message from console
• Server.cfg load order
• Config.Framework value
• Steps to reproduce
• FiveM version