Skip to contentFree server — while stock lasts
mcbalkan.xyz
All articles

08/28/2026

Why your Minecraft server runs out of memory — and how to fix it (2026)

Why your Minecraft server runs out of memory — and how to fix it (2026)

If your Minecraft server crashes under load, refuses to come back after a restart, or dies at exactly the moment it saves the world — the cause is usually not too little RAM. It is that Java was given too much. That sounds backwards. Here is why it happens, and what to set instead.

Java needs memory outside the heap

When your server has 10 GB, you assume the game gets 10 GB. It does not. Java splits it in two.

The first part is the heap — chunks, entities, inventories, everything the game holds in memory. That is what you set with -Xmx.

The second part has no name anyone mentions, and nothing runs without it: the garbage collector's own tables, the code your plugins load (metaspace), the JIT code cache, thread stacks, native libraries. None of it lives in the heap, and all of it spends container memory.

Here is the catch: that second part grows with the heap. The G1 garbage collector needs roughly 4–5% of the heap size for its own bitmaps and tables. On a 10 GB heap that is 400–700 MB, before a single plugin is loaded.

Arithmetic that cannot work

A real example — a 10 GB server with a lot of plugins, on my own infrastructure, last week. It was configured to let the heap take 95% of the container. That sounds generous.

  • Heap: ~10,214 MB
  • Left for Java: ~538 MB
  • G1's tables for that heap alone: 400–700 MB

So the garbage collector eats the entire remainder, and metaspace, the code cache and native libraries get nothing. The kernel kills the container. That is not a risk, it is arithmetic.

I measured what that second part actually uses on two of my servers, one 10 GB and one 2 GB:

  • 10 GB server: 1,630 MB outside the heap — 15.9% of the plan
  • 2 GB server: 327 MB outside the heap — 16.0% of the plan

Two servers five times apart in size, agreeing to within a tenth of a percent. The old setting left 5%.

What it looks like when it goes wrong

You rarely get a message saying "out of memory". You get a chain that looks like three separate faults:

  • The server crashes under load, usually when more players arrive or new terrain generates.
  • The restart finishes it off. Shutting down means saving the whole world — the most memory-hungry moment there is, happening while memory is already full. The save stalls, the timeout expires, the process is killed hard.
  • Then it will not start at all. The crash filled the disk with logs, and a server with no free disk space does not boot.

All three have one cause. Clear the logs and you have fixed the symptom.

How much heap to actually give

The rule is simple: leave Java about a fifth of the plan. I use 80% for the heap on anything above 2 GB, and a little less on small plans where the absolute number matters more than the percentage.

  • 2 GB plan → 1,536 MB heap
  • 4 GB plan → 3,276 MB heap
  • 10 GB plan → 8,192 MB heap
  • 24 GB plan → 19,660 MB heap

I did not invent this. Paper's own documentation says the same thing in different words: if your host says 8 GB, do not set 8 GB — reduce it by 1,000–1,500 MB. For 8 GB they recommend 6,500 MB. My formula gives 6,553 MB at 8 GB. That is 53 MB apart, and we arrived there from two completely different directions.

That is how much of a plan you already have goes to the heap. Which plan to buy in the first place — by player count and server type — I covered in a separate guide.

One more boundary worth knowing: above about 32 GB of heap, Java loses compressed oops, and every reference starts costing eight bytes instead of four. A 34 GB heap holds less than a 31 GB one. Past that point you pay more for less.

Aikar's flags — what they are and why they work

Aikar's flags are a tuning of the G1 garbage collector shaped for Minecraft, and you should take them verbatim from Paper's start script generator rather than copying them off a forum. These are the parts that actually change things:

  • -Xms equal to -Xmx — a fixed-size heap. The server intends to use all of it anyway, so there is no point making the memory grow in steps.
  • -XX:+AlwaysPreTouch — Java claims the whole heap at startup. It sounds wasteful and it is the most useful thing on the list: if the heap does not fit, you find out in the first second rather than in the middle of a world save.
  • -XX:+ParallelRefProcEnabled — reference processing across multiple threads. On a plugin-heavy server that is a classic cause of multi-second freezes.
  • -XX:+DisableExplicitGC — ignores plugins that call System.gc() themselves and stop the whole server doing it.

One note you rarely see: containers mount /tmp as a small RAM-backed disk. Plugins that unpack native libraries write exactly there, and that space counts against container memory. That is why I point temporary files away from it on my servers.

What NOT to do

Three pieces of advice you will find online that make things worse:

  • "Give Java all the RAM." The most common and most expensive advice there is. That exact configuration is what kills a server under load — everything above happens precisely because of it.
  • "More RAM always helps." It does not. Paper says outright that past a point the returns are minimal, and that 32 GB for an ordinary server is wasted money. A badly tuned 8 GB server outperforms a badly tuned 16 GB one.
  • -XX:+HeapDumpOnOutOfMemoryError. It looks useful — capture the state when it breaks. In practice it writes a file the size of your entire heap to disk, fills the quota, and prevents the next start. I never set it.

Where to run all this

If you run your own server: take the flags from Paper's generator and cut -Xmx by a fifth. That is 90% of the work.

On mcbalkan it is already done — the heap is calculated from your plan, it follows the plan if you upgrade, and the flags are exactly the ones Paper publishes. When something does break, you talk directly to me — no ticket queue, no bot. See my Minecraft hosting.