Symptoms: Players complain that "it's lagging", but that is not one single problem. Server lag (low TPS), client lag (the player's FPS is low) and network lag (high ping) are different things. The wrong diagnosis delays the fix.

Possible Causes

  • Server lag (TPS<20): not enough CPU, a heavy plugin, too many entities, a large redstone circuit
  • Network lag (high ping): the VPS is located far away, poor ISP routing, an active DDoS
  • Client lag (low FPS): the player's PC is not up to it, or the shaders/resource pack are heavy — the server is not to blame
  • Chunk loading lag: HDD, high view-distance, no pre-generation done
  • GC pause (lag spike): unsuitable Java heap, a stop-the-world pause
  • Wrong diagnosis: mixing up the type of problem postpones the right fix

Step-by-Step Fix

Step 1

Work out the type of lag first. /tps tells you about the server side, /ping about a player's network latency

bash
/tps
/ping <player>

Step 2

If it is server lag (/tps < 20): use the Spark profiler to find which thread / which plugin is eating the time

bash
/spark profiler --thread * --timeout 60
/spark tps

Step 3

If it is network lag (ping > 200ms): does the VPS location match where your players are? For Turkish players a Frankfurt/Helsinki DC makes sense, a US DC does not

bash
# run this from the player's machine:
ping server-ip
traceroute server-ip

Step 4

If it is client lag (only one player complains, TPS is normal, ping is low): the player's FPS is low. There is no server-side fix. The player should be advised on resource packs / shaders / graphics settings

Step 5

For chunk lag, pre-generate the world — the Chunky plugin is the fastest fix

bash
/chunky radius 5000
/chunky start

Step 6

For GC pauses, keep the heap value fixed and apply Aikar flags. Details: /blog/fixing-minecraft-lag-spikes

bash
-Xms8G -Xmx8G -XX:+UseG1GC [...aikar flags...]

Step 7

For disk I/O lag, look at the await times with iostat. If it is an HDD, moving to SSD is mandatory

bash
iostat -x 2 5

Step 8

If you use Paper, raise the chunk worker threads in paper-global.yml

bash
# config/paper-global.yml
chunk-system:
  io-threads: 2
  worker-threads: 3

Step 9

If you suspect a DDoS, check whether your VPS provider's DDoS protection is active. If traffic shows an abnormal increase, talk to the provider