server thread hitch warning: timer interval of X milliseconds, fix

In the server console or in txAdmin:

server thread hitch warning: timer interval of 1250 milliseconds

The server normally ticks many times per second. This line says one gap between ticks was much longer than it should be, here 1250 ms. This guide covers what it means, the usual causes, how to find the script behind it with the profiler, and when you can ignore it.

#What it means

The server runs your resources on one main thread, and it watches how long it takes to come back around. When something keeps that thread busy, the next tick is late, and the server prints this warning with the length of the delay.

Players notice a hitch as lag: actions that take a moment to answer, vehicles that jump back, and events that arrive late. One number alone says little. Look at how often it appears and how big it gets.

#Common causes

• A heavy server script. A loop that goes through all players, all vehicles or a big table, run again and again, keeps the thread busy. A while true do loop with Wait(0) on the server is a typical offender.
• Slow database work. A resource that asks the database for a lot of data, or runs a very slow query, keeps the thread waiting or processing a large result. Check the slow query warnings that oxmysql prints, and make sure the columns you search have an index.
• Too many entities. Thousands of vehicles, peds or objects that a script spawns and never removes load the server, especially with OneSync.
• A slow machine. A busy CPU, a VPS that shares its cores with others, a slow or full disk, or an antivirus scanning your server folder all add delay that no script is responsible for.
• A very large number of events. A script that fires an event for every player many times per second costs time on both sides.
• The console itself. On Windows, clicking inside the server's console window can pause the process, as the window enters text selection mode. If your hitch warnings come as one long gap and then stop, check you did not click in it. Press Enter or Escape in the window to release it.

Tip: compare the time of the warning with what you did. A hitch each time someone opens a certain menu, or at the same minute every hour, points at the resource behind that action or at a scheduled task.

#Find the culprit with the profiler

FiveM has a built-in profiler. You use it in the server console (the Live Console in txAdmin, or your terminal). Start recording a number of frames while the problem is happening:

profiler record 500

When the recording is done, check it and open it:

profiler status
profiler view

The viewer shows which resources and which functions took the time. Look for a resource whose bar is far longer than the others, then open its functions to see which one spends the time. Check the FiveM documentation for the exact commands and options of your artifact version, as the profiler has more options than listed here, such as saving a recording to a file.

If you do not catch the problem in the act, record again when it is happening, or when you have a lot of players online. A recording while the server is empty usually shows nothing useful.

#A second way: stop resources one by one

When you do not want to read profiler output, find the culprit by elimination. In the server console:

stop my_script

Wait a few minutes and check if the warnings stop. Start it again with ensure my_script. Begin with resources that loop a lot (jobs, HUDs, anything with "sync" or "tick" in its name) and the most recent ones you added.

#Fix the cause

• Heavy loops: make server loops wait longer. Almost nothing needs Wait(0) on the server. Wait(1000) or more is often enough.

CreateThread(function()
    while true do
        Wait(5000)
        -- check things every 5 seconds, not every tick
    end
end)

• Database: use await calls only where you need the result, avoid queries inside a loop and write one query that returns many rows instead of many queries that return one. Add an index to a column you search on in a big table.
• Entities: delete the vehicles and objects a script spawns when it no longer needs them, and set a limit on how many it can create.
• Hardware: if the server has several resources with small hitches and nothing stands out, look at CPU use, disk space, and whether other programs run on the same machine.
• Update: old server artifacts get performance fixes. See update FiveM server artifacts.

#When to ignore it

Warnings during startup are expected. While the server loads dozens of resources, reads their files and connects to the database, the thread is busy for a moment, and a handful of hitch warnings in the first minute does not mean anything is wrong.

Also ignore a rare, small number (a few hundred milliseconds) that appears once in a while, such as during a restart of a big resource. Act when warnings appear while players are online, repeat, or reach seconds.

#Checklist