Troubleshooting

Solutions

Common issues and their solutions for IF Subtitle.

Quick Fix

Most issues can be resolved by ensuring the resource is started correctly and the configuration is valid.

Installation Issues

Resource not starting

Error: "Resource if-subtitle failed to start"

Possible Causes:

• Incorrect folder name
• Missing or corrupted files
• Server version too old

Solutions:

1. Check folder name - Must be exactly if-subtitle

   # Correct:
   resources/if-subtitle/
   
   # Wrong:
   resources/if-subtitle-main/
   resources/IF-Subtitle/

2. Verify all files exist

   if-subtitle/
   ├── fxmanifest.lua
   ├── config.lua
   ├── client.lua (encrypted)
   ├── server.lua (encrypted)
   └── html/ (encrypted)

3. Update your server to build 5000+ (latest recommended)

4. Check server console for specific error messages

"ensure if-subtitle" not working

Make sure the line is added to server.cfg:

ensure if-subtitle

# NOT:
start if-subtitle  # This also works but 'ensure' is recommended

Restart your server completely after editing server.cfg.

Subtitle Issues

Subtitles not showing

Subtitles Don't Appear

Troubleshooting Steps:

1. Test the subtitle system

   -- In client console (F8):
   exports['if-subtitle']:ShowSubtitle('Test', 'If you see this, it works!')

2. Check if the resource is running

   # In server console:
   status if-subtitle
   
   # Or in client console (F8):
   resmon

3. Verify the export syntax

   -- Correct:
   exports['if-subtitle']:ShowSubtitle('Speaker', 'Text')
   
   -- Wrong:
   exports['if_subtitle']:ShowSubtitle(...)  -- Wrong resource name
   TriggerEvent('if-subtitle', ...)  -- Wrong method

4. Check for UI conflicts

   • Temporarily disable other UI resources
   • Check browser console (F8) for JavaScript errors

5. Ensure you're on the client side

   -- Server-side (use export):
   exports['if-subtitle']:ShowSubtitleToPlayer(source, 'Speaker', 'Text')
   
   -- Client-side (use export):
   exports['if-subtitle']:ShowSubtitle('Speaker', 'Text')

Subtitles appear in wrong position

1. Check config.lua

   Config.Position = 'bottom'  -- Make sure this is set correctly

2. Valid positions:

   • 'bottom'
   • 'top'

3. Restart the resource after changing config

   # In server console:
   restart if-subtitle

Subtitles disappear too quickly/slowly

Adjust the duration in config.lua:

Config.DisplayDuration = 5000  -- 5 seconds (default)

Or pass it per-subtitle:

-- For persistent subtitle that won't auto-hide
exports['if-subtitle']:ShowSubtitle('Speaker', 'Text', nil, nil, true)

-- Then manually clear when done
exports['if-subtitle']:ClearSubtitles()

Avatar Issues

Avatar not showing

Avatar Image Not Displaying

Solutions:

1. Use direct image URLs

   -- ✅ Correct (direct link):
   'https://i.imgur.com/example.png'
   
   -- ❌ Wrong (webpage link):
   'https://imgur.com/a/example'

2. Check URL accessibility

   • Open the URL in a browser
   • Should directly show the image, not a webpage

3. Use supported formats

   • ✅ .png, .jpg, .jpeg, .webp
   • ❌ .gif, .bmp, .svg

4. Enable avatars in config

   Config.EnableAvatar = true

Avatar too small/large

Adjust in config.lua:

Config.AvatarSize = 40  -- Size in pixels (default: 40)

Animation Issues

Animation not working

1. Use valid animation names:

   • 'fade' (default)
   • 'slide'
   • 'bounce'
   • 'glow'

2. Check syntax:

   -- Correct:
   exports['if-subtitle']:ShowSubtitle('Speaker', 'Text', nil, nil, nil, nil, 'bounce')
   
   -- Or set default in config:
   Config.DefaultAnimation = 'bounce'

Multi-Speaker Issues

Only one subtitle showing

Enable multi-speaker mode in config.lua:

Config.EnableMultiSpeaker = true
Config.MaxSimultaneousSubtitles = 3  -- Increase if needed

Performance Issues

High resmon usage

Normal Performance

IF Subtitle should show 0.00ms when idle and 0.01-0.02ms when displaying subtitles.

If you're seeing high usage:

1. Check for conflicts with other resources

   • Disable other UI resources temporarily

2. Avoid subtitle spam

   -- Bad (creates infinite subtitles):
   Citizen.CreateThread(function()
       while true do
           exports['if-subtitle']:ShowSubtitle('Spam', 'Bad!')
           Citizen.Wait(0)  -- Too fast!
       end
   end)
   
   -- Good:
   Citizen.CreateThread(function()
       while true do
           exports['if-subtitle']:ShowSubtitle('Good', 'Reasonable rate')
           Citizen.Wait(5000)  -- 5 seconds between subtitles
       end
   end)

Browser/UI Issues

UI not visible or glitched

1. Clear FiveM cache

   • Close FiveM completely
   • Navigate to %localappdata%/FiveM/FiveM Application Data/cache
   • Delete everything in the cache folder
   • Restart FiveM

2. Check for JavaScript errors

   • Press F8 in game
   • Look for red errors in console
   • Screenshot and send to support

3. Verify NUI is enabled

   • Make sure you don't have NUI disabled in any other resources

Still Having Issues?

Get Help

If none of these solutions work:

1. Join our Discord - discord.gg/7FxW9JaDnx
2. Open a support ticket with:
   • Your server.cfg line for if-subtitle
   • Server console logs
   • Client F8 console screenshot
   • Description of the issue
   • Steps to reproduce

We're here to help! 💚