How to Diagnose Crashes and Lag on a FiveM Server
Find the cause of a crash or slowdown on your FiveM Linux server: logs, memory, hitch warnings, resmon, profiler and isolation of the responsible resource.
On this page
Your values
Enter them once and the commands in this guide update.
A FiveM server that crashes or slows down often has a specific cause: a resource, a lack of memory or a saturated machine. This guide gives you a method to find which one: qualify the symptom, read the right logs, measure, then isolate the responsible resource.
Prerequisites
- A server installed with the guide Create a FiveM Server:
fivemuser,fivem.serviceservice, console in/home/fivem/fxserver.log - SSH access with
sudoand access to txAdmin - A recent backup, to make with
sudo /usr/local/sbin/backup-fivem.shbefore changing anything
Qualifying the Symptom
| What you observe | Main lead | Section to read |
|---|---|---|
| The server restarts on its own, all players are disconnected | Process stopped or frozen | Steps 1 to 3 |
| The server no longer starts or stops while loading | Resource or configuration | Step 4 |
| Players see stuttering, vehicles teleporting | Overloaded server | Steps 5 and 6 |
| A single player has a low frame rate | Client side | Step 7 |
| The problem started after an addition or an update | Recent change | Step 8 |
Step 1: Keep the Logs
The /home/fivem/fxserver.log file is emptied each time the service starts. Copy it before restarting anything:
sudo install -o fivem -g fivem -m 640 /home/fivem/fxserver.log "/home/fivem/fxserver-incident-$(date +%F_%H-%M).log"txAdmin also keeps its own logs, with rotation, in /home/fivem/txData/default/logs/:
| File | Content |
|---|---|
fxserver.log |
Server console. Old files have the date in their name |
admin.log |
Administrator actions and automatic restarts |
server.log |
In-game events: connections, deaths, messages, commands |
These files contain player data. Do not publish them as they are.
Step 2: Find Out Why the Server Restarted
Look for the decisions made by txAdmin:
sudo grep -a 'Restarting server' /home/fivem/txData/default/logs/admin.log | tail -n 20| Reason displayed | Meaning | What to do |
|---|---|---|
Server process close detected |
The FXServer process stopped | Look at the end of the console and at memory (step 3) |
Server is not responding |
FXServer is running but no longer responds | Look for a freeze: steps 5 and 6 |
Server is taking too long to start |
Startup exceeds the allowed time | Go to step 4 |
Resource "name" failed to start within the ... time limit |
This resource blocks startup | Test without it (step 8) |
Then read the last lines of the console before the incident, in the copy made in step 1:
sudo bash -c 'ls -t /home/fivem/fxserver-incident-*.log | head -n 1 | xargs tail -n 80'Also look at the service history:
sudo systemctl status fivem.service --no-pager
sudo journalctl -u fivem.service --since "2 days ago" --no-pager | tail -n 40Step 3: Check Memory and Disk
When memory runs out, the Linux kernel kills a process. Look for its trace:
sudo journalctl -k --since "2 days ago" --no-pager | grep -iE 'out of memory|oom-kill|killed process'
free -h
df -h /home /var/lib/mysql- An
Out of memory: Killed processline appears: the server is running out of memory. Look for a resource whose consumption keeps growing, then reduce the load or increase the machine's memory. - A disk is 100% full: free up space. MariaDB and the logs can no longer write.
To follow FXServer's memory over time, run this command at several moments. txAdmin and the game server appear as two processes, the bigger one usually being the game server:
ps -u fivem -o pid,pcpu,pmem,rss,etime,args --sort=-rss | cut -c1-110An RSS column that climbs without ever going back down, while the number of players stays stable, points to a memory leak in a resource.
Step 4: Analyze a Failing Startup
Display the latest loading events:
sudo grep -a -E "Started resource|Could not (find|start) dependency|Couldn't (find|start) resource|can't run|Failed to load script|SCRIPT ERROR" /home/fivem/fxserver.log | tail -n 30| Message | Cause | Solution |
|---|---|---|
Couldn't find resource name. |
The folder does not exist, or its name differs from the ensure line |
Fix server.cfg or the folder, then type refresh |
Couldn't start resource name. |
Startup failed | Read the lines just above |
Could not find dependency x for resource y. |
Resource x is missing |
Install it |
Could not start dependency x for resource y. |
Resource x exists but does not start |
Deal with x first |
Resource 'name' can't run: |
A condition is not met, for example server needs to be 12913 or higher |
Update FXServer Artifacts |
Failed to load script file. |
Missing or invalid file | Reinstall the resource |
SCRIPT ERROR: |
Error in a script's code | The message gives the file and line: update it or report it to its author |
For a database error, see Install and Configure oxmysql on FiveM.
Step 5: Spot Server Slowdowns
FXServer reports delays in its internal loops with hitch warnings:
sudo grep -a -c 'hitch warning' /home/fivem/fxserver.log
sudo grep -a 'hitch warning' /home/fivem/fxserver.log | tail -n 20| Message | Triggered from | Concerns |
|---|---|---|
server thread hitch warning |
150 ms | Main loop, where server scripts run |
network thread hitch warning |
150 ms | Network |
sync thread hitch warning |
100 ms | OneSync synchronization |
An isolated warning at startup or during a resource restart is not worrying. Regular warnings in game are. Cfx.re most often attributes them to a poorly performing resource, for example an overly costly loop or a slow SQL query.
Before blaming a resource, check that the machine is not saturated:
uptime
vmstat 1 10In vmstat, look at three columns:
| Column | High value |
|---|---|
id |
Low: the processor is almost fully busy |
wa |
The processor is waiting for the disk |
st |
Processor time is taken by the hypervisor |
Then look at the thread details, replacing PID with the number of the biggest process noted in step 3. Quit with q:
top -H -p PIDA single thread near 100% indicates that a server loop is saturated, even if the machine has other free cores. In that case, adding cores helps little: it is better to lighten the scripts. If wa or st stay high while the server is lightly loaded, contact support from your customer area, with your measurements.
Also check the slow queries reported by oxmysql:
sudo grep -a 'to execute a query' /home/fivem/fxserver.log | tail -n 20Step 6: Record a Server Profile
The built-in profiler shows which resource consumes the time. Run it in Live Console while the problem is happening, with players connected if possible:
profiler record 500
profiler statusWait until profiler status shows Recording: No, then save the result:
profiler saveJSON server-profile.jsonThe file is created in the server folder, whose name ends in .base. On the server, copy it to your home folder, replacing FOLDER_NAME:
sudo find /home/fivem/txData -maxdepth 1 -type d -name '*.base'
sudo install -o "$USER" -m 600 /home/fivem/txData/FOLDER_NAME.base/server-profile.json "$HOME/server-profile.json"
sudo rm /home/fivem/txData/FOLDER_NAME.base/server-profile.jsonThen retrieve it from your computer:
scp YOUR_USER@SERVER_IP:server-profile.json .Open Google Chrome, then the developer tools with F12. In the Performance tab, load the file with Load profile. Spot the peaks in the activity graph, zoom in on them, then read the names of the longest resources and functions.
Step 7: Measure on the Player Side with resmon
resmon displays the cost of each resource on the client. It helps with frame rate drops, not with server delays.
In the game, open the console with F8 and type:
resmon trueSort by CPU msec or Time % to spot costly resources, and look at Memory for memory. Type resmon false to close it.
If the console answers Access denied for command resmon, developer mode is not active on your client. Launch FiveM with the +set moo 31337 argument. With FiveM for GTA V Enhanced, this argument no longer exists and the server must set sv_devMode true.
The txAdmin Player Drops page complements this analysis: it shows whether players leave the server because of crashes of their game, and since when.
Step 8: Isolate the Responsible Resource
Start with what changed recently. If nothing changed, proceed by halves.
Quick Test on the Running Server
For a secondary resource, stop it in Live Console, then watch for warnings for about ten minutes:
stop resource_nameThen restart it with ensure resource_name. Do not stop oxmysql, es_extended, qb-core or another resource that many others depend on in this way: you would cause errors unrelated to the problem.
Searching by Halves
First make a copy of the configuration, replacing FOLDER_NAME:
sudo -u fivem cp /home/fivem/txData/FOLDER_NAME.base/server.cfg /home/fivem/txData/FOLDER_NAME.base/server.cfg.before-diagnosticThen, outside peak hours:
- In CFG Editor, disable half of the optional resources by adding
#in front of theirensureline. Keep the framework and its dependencies. - Restart the server and try to reproduce the problem.
- If the problem disappears, it comes from the disabled half. Otherwise, it comes from the one that remains active.
- Repeat on the suspect group, until only one resource is left.
If several resources are launched by a folder, such as ensure [addons], temporarily replace this line with one ensure line for each of them. A Could not find dependency error during the test simply means that you disabled a dependency: re-enable it.
Once you have found the resource, update it, fix its configuration or report the problem to its author, with your profile and logs. Then put the original configuration back, then restart the server from txAdmin:
sudo -u fivem cp /home/fivem/txData/FOLDER_NAME.base/server.cfg.before-diagnostic /home/fivem/txData/FOLDER_NAME.base/server.cfgAsking for Help
For a resource problem, contact its author or the Cfx.re forum. Prepare:
- the FXServer build and the txAdmin version, noted as in Update FXServer Artifacts
- the time of the incident and what changed just before
- the relevant console lines, the profile and the results of
free -handvmstat
Cfx.re points out that the Linux version of FXServer is a port offered for convenience: if a defect comes from FXServer itself, it is more likely to be fixed if it is reproduced on Windows. Also check that it persists on the latest recommended version before reporting it.
Troubleshooting During Diagnosis
profiler saveJSON returns Invalid path
Use a simple file name, without a folder, and check that the fivem user can write to the server folder.
A recording is already taking place
A recording is already in progress. Wait for it to end with profiler status, or stop it with profiler record stop.
The fxserver.log file is empty
The service has just restarted. Use /home/fivem/txData/default/logs/fxserver.log, as well as the dated files in the same folder.
The server restarts in a loop during the tests
Stop it with sudo systemctl stop fivem.service, put server.cfg.before-diagnostic back in place with the command above, then restart the service with sudo systemctl start fivem.service.