Minecraft Server Troubleshooting Guide
Fix the most common Minecraft server problems — won't start, can't connect, lag, crashes, and mod errors.
Server Won't Start
| Error | Cause | Fix |
|---|---|---|
UnsupportedClassVersionError | Wrong Java version | Change Java version |
Failed to bind to port | Port already in use | Restart the server or contact support |
EULA not accepted | EULA not agreed to | Set eula=true in eula.txt |
OutOfMemoryError | Not enough RAM | Increase RAM allocation in Startup |
| Plugin/mod crash on startup | Incompatible mod or plugin | Check console for the specific error, remove the problematic file |
Can't Connect
| Issue | Fix |
|---|---|
| "Can't resolve hostname" | Check server IP is correct |
| "Connection timed out" | Server not running, or port blocked |
| "Connection refused" | Server crashed or port wrong |
| "Outdated server/client" | Version mismatch — match your client to server |
| "Failed to verify username" | online-mode=true requires a legit account |
| "You are not whitelisted" | Ask admin to run whitelist add YourName |
| "Server is full" | Max players reached — ask admin to increase |
Lag / Low TPS
- Install Spark and run
/spark profiler start - Wait 5 minutes, then
/spark profiler stop - Check the report for the biggest time consumers
Quick fixes:
- Reduce
view-distanceandsimulation-distance - Apply Aikar's JVM flags
- Pre-generate chunks
- Remove laggy mods/plugins identified by Spark
World Corruption
- Restore from a backup if available
- Use MCA Selector to identify and delete corrupted chunks
- See Reset Chunks guide
YAML / JSON Errors
Config file syntax errors crash plugins. Common mistakes:
- Using tabs instead of spaces in YAML
- Missing quotes around strings with special characters
- Mismatched brackets in JSON
Use an online YAML or JSON validator to check your files.
💡 Tip: Check the Console output — error messages almost always point to the exact file and line number causing the problem.
Related Guides
How is this guide?
40% Off — Limited TimeGet your Minecraft server todayInstant setup, DDoS protection, and 24/7 support included.
Get a Server