Heap memory and Java GC: why your server runs out of breath

Minecraft runs inside the Java Virtual Machine, which manages memory through a system called garbage collection. When memory is managed poorly, the garbage collector's cleanup cycles cause brief server freezes that players experience as lag spikes. Understanding how this works is the first step to preventing it.

How Java memory works

Java allocates a pool of memory called the heap at startup. You set the maximum size with the -Xmx flag, for example -Xmx6G for 6 gigabytes. As the server runs, objects are created, used, and discarded. The garbage collector periodically reclaims memory from discarded objects.

Paper uses the G1GC garbage collector by default. It runs mostly in the background, but when the heap approaches capacity, G1GC triggers a more aggressive full collection. During a full collection, the JVM pauses everything, including the main server thread, for however long the cleanup takes.

What GC pauses do to TPS

A GC pause of 200ms means the server did not tick for 200ms. That single missed-tick window shows up as a TPS drop in your charts. If GC pressure is chronic, where the heap fills faster than it's being freed, you'll see repeated TPS dips that correlate with memory peaks on the heap chart.

clan.me tracks cumulative GC pause time between heartbeats and surfaces it as a GC pressure metric. A server with no GC pressure at 80% heap is fine. A server with high GC pressure at 60% heap is about to have problems.

Reading the memory chart

The memory chart plots heap used vs heap max over time. clan.me also runs a linear regression on the trend and estimates time to 90% ceiling. That projection is a heads-up, not a prediction, since sudden changes like a mob farm going active can change the trajectory quickly. Check the GC pressure chart alongside memory to understand whether heap growth is being managed.

Sizing your heap

General starting points for Paper servers, adjusting for your specific plugin load:

• Under 10 players: 3 to 4 GB
• 10 to 30 players: 5 to 6 GB
• 30 to 60 players: 7 to 10 GB
• 60 or more players: 10 GB and above, depending on world count and plugin complexity

Do not set -Xmx above 12 to 14 GB without also switching to ZGC or Shenandoah. G1GC's pause times scale with heap size, and very large heaps can produce GC pauses of several seconds.

Set a memory pressure alert in clan.me to receive a notification when your heap reaches 85% of max, before GC pauses start affecting players.