FiveM stuck on the loading screen: causes and how to debug it

Players connect, the bar fills, and then nothing: the loading screen stays up forever, or the game freezes on a black screen. This guide goes through the causes in the order that is quickest to rule out, and shows how to use F8 and the server console to find the one you have.

#First: is it everyone or one player?

• Everyone is stuck. The cause is on the server: a resource, the framework, or a loadscreen.
• One player is stuck. Look at that player's client: cache, a slow connection, mods, or an old game build. Start with clearing the FiveM cache.

Join once yourself and press F8. This works on the loading screen too. Read what is printed there, and keep the server console open on the other side.

#1. A script error on the client

F8 lists client errors. Any line like this during loading is a strong clue:

SCRIPT ERROR: @my_script/client/main.lua:25: attempt to index a nil value (global 'ESX')

A client script that crashes in its start thread can leave the spawn flow unfinished. Fix the script named in the error: the guides for reading a script error, ESX nil and QBCore nil cover the common ones. Then restart the resource and rejoin.

Test by elimination if nothing is printed: stop the most recently added or changed resource, rejoin, and see if the loading finishes.

#2. Nobody spawns the player

After loading, something must spawn the player and turn the loading screen off. Usually:

• spawnmanager does it in a plain server.
• A framework's multicharacter and spawn selector do it on ESX and QBCore.

Check that these resources start, in the right order, and that only one of them handles spawning. A typical conflict is a default spawnmanager auto-spawning the player while a multicharacter resource also wants to. Make sure the base resources are started before the framework, as in the right ensure order:

ensure oxmysql
ensure ox_lib
ensure es_extended        # or qb-core / qbx_core
ensure spawnmanager
ensure esx_multicharacter # or qb-multicharacter / qbx_core's own

If a multicharacter resource stalls, look at the server console for a database error from it: character loading reads the database, and a SQL failure leaves the player waiting. See oxmysql connection error and SQL table doesn't exist.

#3. A custom loadscreen that never closes

Server loadscreens are resources declared in their manifest:

fx_version 'cerulean'
game 'gta5'

loadscreen 'html/index.html'
loadscreen_manual_shutdown 'yes'

files { 'html/**/*' }

With loadscreen_manual_shutdown 'yes', FiveM does not close the loadscreen on its own. A client script has to do it, by calling the shutdown natives once the player is ready:

ShutdownLoadingScreen()
ShutdownLoadingScreenNui()

If a loadscreen resource has the manual shutdown option and nobody calls these, the screen stays up forever. Either remove loadscreen_manual_shutdown, or make sure your spawn flow calls them. Test by stopping the loadscreen resource and rejoining.

A loadscreen that is broken, that loads an external file which is unreachable, or that plays a very large video can also block or slow the screen down. Keep it light and local.

#4. Large streaming and downloads

Joining downloads all streamed files the player does not have yet. A server with many large vehicles, maps and clothing packs can take minutes on first connect, and the loading screen shows nothing happening if the download is slow. Signs:

• The F8 or loading screen shows downloads in progress.
• It works for returning players but not for new ones.
• The problem gets worse after you add a pack of assets.

Fixes: reduce the size and the count of streamed assets (see oversized assets), host the server on a connection with enough bandwidth, and ask players to wait for the first download to finish.

#5. Game build or server version problems

If the server forces a game build, a player on an older or different build may fail to join cleanly. Check sv_enforceGameBuild in server.cfg against the DLC your assets need. See sv_enforceGameBuild. An outdated server artifact can also cause odd joins: update your artifacts.

#6. The framework does not load the character

Players spawn, but the framework never finishes loading the player. In the server console look for:

• a database error while loading the player or character
• an error from es_extended, qb-core or qbx_core on the player-loaded event
• a script that hooks that event and throws, stopping other handlers

If you see an error there, fix it, and rejoin. A broken inventory or a broken job script can also fail inside the player-loaded flow, so check the most recently added ones first.

#A debug routine

1. Join and press F8. Note every error.
2. Read the server console during the join.
3. Stop the most recently changed resource, rejoin.
4. Stop the loadscreen resource, rejoin.
5. Still stuck for everyone: start with only the base resources and add the rest back in groups.

Tip: if you add resources in groups of five or ten, you find the bad one with a few restarts instead of testing 80 resources one by one.

#Checklist