Troubleshooting Checklists

Use these interactive checklists to systematically troubleshoot issues. Your progress is saved locally in your browser.

Server Won’t Boot

If your FiveM server fails to start, work through this checklist in order:

License key configured - Verify sv_licenseKey in server.cfg matches your key from keymaster.fivem.net
Ports not in use - Check if port 30120 is already in use: sudo lsof -i :30120 or sudo netstat -tulpn | grep 30120
Database running and accessible - Verify MariaDB/MySQL is running: sudo systemctl status mariadb (or mysql)
Resources exist and are valid - Check that all resources in server.cfg exist in the resources/ directory
Server.cfg syntax correct - Validate no missing quotes, brackets, or typos. Check for trailing commas in arrays
Sufficient disk space - Check available space: df -h. FiveM needs at least 5GB free for logs and cache
Sufficient memory - Check RAM usage: free -h. FiveM server needs at least 2GB RAM available
Check server logs for errors - Review /opt/fivem/logs/server.log or txAdmin console for specific error messages

How to verify each item:

License key configured:


# Check server.cfg
grep "sv_licenseKey" /opt/fivem/server.cfg
# Should show: set sv_licenseKey "your-key-here"
# Verify key at: https://keymaster.fivem.net/

Ports not in use:


# Find process using port 30120
sudo lsof -i :30120
# If output shows a process, kill it: sudo kill -9 <PID>
# Or use: sudo fuser -k 30120/tcp

Database running:


# Check service status
sudo systemctl status mariadb
# or
sudo systemctl status mysql
 
# Test connection
mysql -u root -p -e "SELECT 1;"

Resources exist:


# List resources in server.cfg
grep "^ensure\|^start" /opt/fivem/server.cfg | awk '{print $2}' | while read res; do
  if [ ! -d "/opt/fivem/resources/$res" ]; then
    echo "Missing: $res"
  fi
done

Server.cfg syntax:


# Basic syntax check (look for common errors)
# Check for unclosed quotes
grep -n '"' /opt/fivem/server.cfg | awk -F'"' 'NF%2==0 {print "Possible unclosed quote at line", NR}'

Disk space:


df -h /opt/fivem
# Ensure at least 5GB free (10GB+ recommended)

Memory:


free -h
# Check "available" column, should be >2GB

Check logs:


# View last 50 lines of server log
tail -n 50 /opt/fivem/logs/server.log
 
# Search for errors
grep -i "error\|failed\|exception" /opt/fivem/logs/server.log | tail -20

Players Can’t Join

If players cannot connect to your server, verify these items:

Server is running - Verify FXServer process is active: ps aux | grep FXServer
Firewall allows port 30120 - Check UFW: sudo ufw status | grep 30120, or firewalld: sudo firewall-cmd --list-ports
Port forwarding configured (if needed) - For home servers, configure router to forward port 30120 TCP/UDP to server IP
Server not full - Check current players: In-game or via txAdmin. Verify sv_maxclients setting in server.cfg
License key valid - Verify key hasn't expired or been revoked at keymaster.fivem.net
Network connectivity - Test from external network: nc -zv your-server-ip 30120 (should succeed)
Check server logs - Look for connection attempts, authentication failures, or bans in server.log

How to verify each item:

Server is running:


# Check process
ps aux | grep FXServer
# Should show FXServer process
 
# Check systemd service
sudo systemctl status fivem
# Should show "active (running)"

Firewall allows port:


# UFW
sudo ufw status | grep 30120
# Should show: 30120/tcp and 30120/udp ALLOW
 
# firewalld
sudo firewall-cmd --list-ports | grep 30120
# Should include: 30120/tcp 30120/udp

Port forwarding:
- Log into your router admin panel
- Navigate to Port Forwarding/Virtual Server
- Verify rule exists: External Port 30120 → Internal IP:Port (your-server-ip:30120)
- Test from external network: nc -zv your-public-ip 30120

Server not full:


# Check server.cfg
grep "sv_maxclients" /opt/fivem/server.cfg
# Default is usually 32 or 64
 
# Check current players via txAdmin or in-game

License key valid:
- Visit https://keymaster.fivem.net/
- Log in and check your license key status
- Verify it matches the key in server.cfg
- Check expiration date

Network connectivity:


# From external machine (not your server)
nc -zv your-server-ip 30120
# Should return: Connection to your-server-ip 30120 port [tcp/*] succeeded!
 
# Test from server itself
nc -zv localhost 30120

Check server logs:


# Look for connection attempts
grep -i "connect\|join\|player" /opt/fivem/logs/server.log | tail -20
 
# Check for authentication errors
grep -i "auth\|license\|key" /opt/fivem/logs/server.log | tail -20

Database Errors

If you’re experiencing database connection or query errors:

Database service running - Check MariaDB/MySQL service: sudo systemctl status mariadb
Credentials correct - Verify database username, password, and host in resource configs match database settings
Database exists - Connect to MySQL and list databases: mysql -u root -p -e 'SHOW DATABASES;'
Tables created (imported SQL) - Verify tables exist: mysql -u root -p database_name -e 'SHOW TABLES;'
Firewall allows database port - Default MySQL port 3306 should be open for localhost (127.0.0.1)
Connection string correct - Check resource configs use format: mysql://user:pass@host:port/database
Check database logs - Review MySQL error log: sudo tail -f /var/log/mysql/error.log

How to verify each item:

Database service running:


# Check service status
sudo systemctl status mariadb
# or
sudo systemctl status mysql
 
# Should show "active (running)"
 
# Start if stopped
sudo systemctl start mariadb

Credentials correct:


# Test connection with credentials
mysql -u your_username -p -h localhost
# Enter password when prompted
# Should connect successfully

Database exists:


# List all databases
mysql -u root -p -e "SHOW DATABASES;"
 
# Check for your FiveM database (usually 'fivem' or framework name)
mysql -u root -p -e "SHOW DATABASES LIKE 'fivem';"

Tables created:


# List tables in database
mysql -u root -p fivem -e "SHOW TABLES;"
 
# Should show tables like: users, vehicles, items, etc.
 
# If empty, import SQL files from framework/resources

Firewall database port:


# For local connections, port 3306 should be accessible from localhost
# Test connection
mysql -u root -p -h 127.0.0.1 -e "SELECT 1;"
 
# If using remote database, ensure firewall allows:
sudo ufw allow from your-app-ip to any port 3306

Connection string:


# Check resource configs (example for oxmysql)
grep -r "mysql://" /opt/fivem/resources/*/config.*
 
# Format should be: mysql://username:password@host:port/database
# Example: mysql://fivem:password123@localhost:3306/fivem

Check database logs:


# MySQL error log location varies by distro
# Ubuntu/Debian
sudo tail -f /var/log/mysql/error.log
 
# CentOS/RHEL
sudo tail -f /var/log/mariadb/mariadb.log
 
# Look for connection errors, authentication failures, or query errors

Resource Errors

If resources fail to start or function incorrectly:

Resource exists in resources folder - Verify directory exists: ls -la /opt/fivem/resources/resource-name
fxmanifest.lua valid - Check syntax: lua -l /opt/fivem/resources/resource-name/fxmanifest.lua (should not error)
Dependencies installed - Verify all dependencies listed in fxmanifest.lua exist in resources folder
Dependencies started - Check server.cfg ensures dependencies before this resource: ensure dependency1, ensure dependency2, ensure resource-name
Scripts syntax correct - Check for Lua/JS syntax errors. Use: lua -l script.lua or node --check script.js
Check resource logs - Review resource-specific logs or server.log for this resource's errors

How to verify each item:

Resource exists:


# List resources
ls -la /opt/fivem/resources/
 
# Check specific resource
ls -la /opt/fivem/resources/your-resource-name/
# Should show: fxmanifest.lua, client/, server/, etc.

fxmanifest.lua valid:


# Basic syntax check (Lua will parse it)
lua -e "dofile('/opt/fivem/resources/your-resource-name/fxmanifest.lua')"
# Should not produce errors
 
# Check for common issues:
# - Missing quotes around strings
# - Unclosed brackets
# - Invalid fx_version

Dependencies installed:


# Check fxmanifest.lua for dependencies
grep -i "dependency\|depend" /opt/fivem/resources/your-resource-name/fxmanifest.lua
 
# Verify each dependency exists
# Example output: dependency 'oxmysql'
# Then check: ls -d /opt/fivem/resources/oxmysql

Dependencies started:


# Check server.cfg order
grep -n "ensure\|start" /opt/fivem/server.cfg
 
# Dependencies should appear BEFORE the resource that needs them
# Example:
# ensure oxmysql
# ensure your-resource-name  # <- This comes after dependencies

Scripts syntax:


# For Lua files
lua -l /opt/fivem/resources/your-resource-name/client/client.lua
# Should not produce syntax errors
 
# For JavaScript files
node --check /opt/fivem/resources/your-resource-name/client/client.js
# Should return no errors
 
# Check all scripts in resource
find /opt/fivem/resources/your-resource-name -name "*.lua" -exec lua -l {} \;

Check resource logs:


# Server log filtered for this resource
grep -i "your-resource-name" /opt/fivem/logs/server.log | tail -20
 
# Look for:
# - "Started resource your-resource-name"
# - Error messages specific to this resource
# - Missing file errors
# - Export/import errors

Still Need Help?

If you’ve completed all relevant checklists and the issue persists:

Gather information:
- Server logs (last 100 lines)
- Resource error messages
- System resource usage (CPU, RAM, disk)
- Network connectivity test results
Check additional resources:
- Common Errors - Solutions to specific error messages
- FiveM Forums - Community support
- Framework-specific documentation (QBCore, ESX, etc.)
Provide details when asking for help:
- What you’ve already checked (from checklists above)
- Exact error messages from logs
- Steps to reproduce the issue
- Server configuration (framework, resources, etc.)