Minecraft Server Troubleshooting Guide: Common Problems and Fixes
Index of the most common Minecraft Java server issues — won't start, can't connect, lag, crashes, mod errors — with links to detailed fix guides.
This is the starting point for any Minecraft server problem. Each row in the tables below points to a detailed guide for the specific issue. If you're not sure what's wrong, scan the symptoms below and click through to the matching fix.
Server Won't Start
| Error in Console | Cause | Fix |
|---|---|---|
You need to agree to the EULA | EULA not accepted | Accept the EULA |
UnsupportedClassVersionError | Wrong Java version | Java Version |
OutOfMemoryError / Exit code 137 | Not enough RAM | How Much RAM |
Failed to bind to port / Address already in use | Port conflict | Restart from Dashboard, contact support if persistent |
| Crash on plugin load | Incompatible or broken plugin | Remove the most recent plugin, see Server Won't Start |
Failed to check session lock | Lock file from unclean shutdown | Session Lock |
Exception in server tick loop | Watchdog killed a hung tick | Server Tick Loop |
Ticking entity crash | Corrupted entity in world | Fix Ticking Entity |
| Crash with no clear error | Read first error in log | Server Won't Start |
Can't Connect
| Error in Minecraft client | Cause | Fix |
|---|---|---|
Connection refused | Server offline, wrong port, full | Connection Refused |
Connection timed out | Wrong IP, DNS, network blocking | Connection Timed Out |
Can't resolve hostname | DNS misconfigured | Custom Server IP |
Outdated server / Outdated client | Version mismatch | Switch Version |
Failed to verify username | online-mode mismatch | Failed Verify Username |
You are not whitelisted on this server | Whitelist enabled | Whitelist Setup |
Server is full | max-players reached | Player Limit |
You are banned from this server | IP or name ban | Ban / Unban Players |
Kicked for flying | Anti-cheat false positive | Kicked for Flying |
Lag and Performance
| Symptom | Type of lag | Fix |
|---|---|---|
| Everyone lags simultaneously | Server (TPS) | Optimize Server |
TPS below 18 in /spark tps | Server (TPS) | Setup Spark → find culprit |
| One player lags, others don't | Network (player ping) | Player's local network |
| Stuttering when exploring new chunks | Chunk generation | Pre-generate Chunks |
| Lag near a mob farm | Entity tick load | Mob Spawn Rate, FarmControl |
Can't keep up! warnings | Server overloaded | Server Tick Loop |
| Frequent OOM kills | RAM pressure | How Much RAM, JVM Flags |
See also: Types of Server Lag.
Crashes and World Corruption
| Issue | Where to look | Fix |
|---|---|---|
| Server crashed | crash-reports/ folder | Find / Read Crash Reports |
| Crash on world load | Crash report mentions world/entity | Fix Ticking Entity |
| Corrupted chunks | World data | Restore from Backups, or Reset Chunks |
level.dat errors | World folder | Replace with level.dat_old, restore backup |
| Need to read what crashed | logs/latest.log | Find / Share Server Logs |
| Need to share logs for help | mclo.gs | Find / Share Server Logs |
Config File Errors
| File type | Issue | Fix |
|---|---|---|
YAML (.yml) | "Invalid configuration" / "could not load" | Find / Fix YAML Errors |
JSON (.json) | "Failed to parse" / "unexpected token" | Find / Fix JSON Errors |
server.properties | "Failed to load" | Check for stray characters, save as plain text |
eula.txt | EULA not accepted | Accept the EULA |
Plugins and Mods
| Issue | Fix |
|---|---|
| Plugin won't load | Check Console for the error, see Find / Fix YAML Errors |
| Mod won't load | Check Java/MC version compatibility, see Mod Setup |
| Forge mods + Bukkit plugins together | Use a hybrid JAR — see Install Custom JAR |
| Plugin causes server lag | Setup Spark → identify, then update or remove |
| Plugin requires a database | Use MySQL Database |
BungeeCord / Velocity Networks
| Issue | Fix |
|---|---|
| Setting up a network | BungeeCord Setup |
| IP forwarding broken | BungeeCord IP Forwarding |
If you wish to use IP forwarding... | BungeeCord Troubleshooting |
| Backend not reachable from proxy | BungeeCord Troubleshooting |
The Universal First Step
Read the Console. Almost every problem on a Minecraft server is logged in Console in the XGamingServer Panel. Read the first error message — later ones are usually side effects.
If you can't make sense of it, share the log via mclo.gs and ask in our Discord.
Related Guides
How is this guide?
How to Enable Command Blocks on Your Minecraft Server
Enable command blocks on your Minecraft Java server, get them in survival, and use them safely with OP-only restrictions.
How to Use the Config Editor on Your Minecraft Server
Edit server.properties, spigot.yml, paper-global.yml, and other config files using the visual Config Editor in the XGamingServer panel.