Symptoms: There is a problem with your Minecraft server but you do not know exactly what kind it is: it could be connection, lag, plugin, config, world or security related. This page is for pinning down the type of problem quickly and pointing you to the right sub-guide.

Possible Causes

  • Installation error — Java version, RAM setting, EULA acceptance, port conflict
  • Configuration error — server.properties, YAML syntax, conflicting settings
  • Performance problem — not enough resources, bad Java flags, a heavy plugin
  • Connection problem — firewall, port forwarding, online-mode, proxy (BungeeCord/Velocity)
  • Plugin / API incompatibility — an old plugin crashing on a newer MC version
  • World or data corruption — corrupted chunks, missing player files
  • Security incident — DDoS, unauthorized access, whitelist bypass

Step-by-Step Fix

Step 1

Every diagnosis starts with reading the logs. logs/latest.log tells you what the server did and where it got stuck

bash
tail -100 logs/latest.log

Step 2

If the server does not start at all: look at the installation category — Java, EULA, port. Related pages: Java Version Error, EULA Not Accepted, Port Already In Use

bash
# Java:
java -version
# EULA:
cat eula.txt
# Port:
ss -tlnp | grep 25565

Step 3

If players cannot connect: check the firewall + port + IP. Details: /blog/cant-connect

bash
sudo ufw status
curl -s ifconfig.me

Step 4

It starts but there is lag: the performance category. Details: /blog/fixing-minecraft-server-lag, /blog/tps-drop

bash
/tps
/spark tps

Step 5

If there is a plugin problem — a command not working or a permission error: /blog/plugin-not-loading, /blog/permission-denied

bash
/plugins
grep -i "plugin" logs/latest.log | tail -20

Step 6

Permissions or ranks not showing: trace it with LuckPerms verbose

bash
/lp verbose on

Step 7

For world corruption or chunk errors: /blog/world-corruption, /blog/backup-restore

Step 8

For a problem that fits none of these specific areas, take a deep profile with Spark and upload the report to the KEYDAL Spark Analyzer

bash
/spark profiler --thread * --timeout 120

Step 9

If you cannot solve it on your own, write to the KEYDAL Projects team — the first diagnosis is free