OutOfMemoryError on Your Minecraft Server: Finding the Real Cause

First: which kind of memory error is it?

Four completely different things all get called "the server ran out of memory" - and their fixes point in opposite directions. Working out which one you have is the whole job.

What you see	What it is	Which way do you go?
A Java error with OutOfMemoryError in logs/latest.log	The heap is full	Give it more memory, or find the leak
The log stops mid-line, the panel says Killed or exit code 137	The system killed the server	Give Java less
The server never reached Starting minecraft server version	It could not start with that much memory	Lower -Xmx
A watchdog message about a long tick	Not a memory error	It is a performance problem

The biggest trap in this guide: with exit code 137, the instinctive reaction - giving Java more RAM - is exactly wrong, and it makes the error happen sooner.

---

java.lang.OutOfMemoryError: Java heap space

It usually appears in the log like this:

Exception in thread "Server thread" java.lang.OutOfMemoryError: Java heap space

What it means: the memory you gave Java with -Xmx is genuinely full of data that is still in use. Either the number is too low for what the server is doing, or something is holding on to data that should have been cleared away.

The server rarely dies cleanly from this. It throws the error, TPS falls towards zero, and the process limps along. A great many "my server is frozen but still shows as online" tickets are a server after a heap space error.

---

java.lang.OutOfMemoryError: GC overhead limit exceeded

What it means: Java spent more than 98% of its time cleaning up memory and recovered less than 2% each time - five times in a row. It is really the same situation as Java heap space, just caught slightly earlier.

For your players, the minutes leading up to it felt like severe lag.

Same diagnosis and same fix as above.

There is a Java option that disables the check. Do not use it. It does not remove the problem - it trades a fast failure for a server that runs on at zero TPS indefinitely.

---

java.lang.OutOfMemoryError: Metaspace

What it means: this is not about -Xmx. Metaspace is where Java stores the code from your plugins and mods, and it sits outside the heap.

The two causes:

1. You are reloading plugins. Every time you run /reload or use a plugin-manager plugin, all the code is loaded afresh. If the old copy is not cleared away - and often it is not - Metaspace grows with every single reload until the server dies. This is by far the most common cause.
2. A very large modpack with thousands of classes, combined with a limit set by the control panel.

Counter-intuitively: here it can help to lower -Xmx. Metaspace sits outside the heap, so giving the heap less room leaves more for Metaspace.

The fix is behaviour, not settings: use /reload for configuration changes, and restart when you swap a plugin.

---

Could not reserve enough space for object heap

Error occurred during initialization of VM
Could not reserve enough space for object heap
Error: Could not create the Java Virtual Machine.

What it means: Java could not get hold of the memory you asked for at all. This happens before the server starts - there is no OutOfMemoryError, and nothing at all is written to logs/latest.log.

The tell: the server never reaches the line Starting minecraft server version....

Causes:

1. -Xmx is larger than the plan you have. By far the most common.
2. There are two different -Xmx values in the startup line
3. The unit is written wrong - it is -Xmx4G, not -Xmx4GB

---

Killed and exit code 137

In the panel it typically looks like this:

Killed

or

Exit code: 137
Out of memory: true

What it means: this is not Java giving up - it is the system killing the server, because the whole process was larger than your plan allows. 137 means "killed from outside".

How to tell them apart:

	Java error (OutOfMemoryError)	The system killed it (137)
Who decided	Java, because the heap was full	The system, because the whole process was too big
In the log	A Java error with a stack trace	Nothing - the log stops mid-line
Did it save?	Usually partially	No - risk of corrupted chunks
The fix	Give it more, or find the leak	Give Java less

The server did not get to save. Check your world, and consider restoring from backup if something looks wrong.

The fix: lower -Xmx by 1-2 GB, or move to a larger plan. Not the opposite.

---

The watchdog message is not a memory error

On Paper it looks like this:

The server has stopped responding! This is (probably) not a Paper bug.

On vanilla:

A single server tick took 60.00 seconds (should be max 0.05)
Considering it to be crashed, server will forcibly shutdown.

The watchdog measures time, not memory. It fires when a single tick takes too long - a slow database query, a large WorldEdit operation, chunk generation.

But there is a connection you need to know: a nearly full heap causes constant cleanup pauses, which stall ticks, which trips the watchdog. So always look upwards in the log. If there is an OutOfMemoryError above the watchdog message, memory is the real story. If there is a plugin in the thread dump, it is a genuine performance problem.

---

How much may you give Java?

Two rules, and the second one is broken constantly.

1. Set -Xms and -Xmx to the same number. A heap that grows along the way causes a pause every time it expands. The server reaches the maximum within minutes anyway, so there is nothing to save.

2. Never give Java your whole plan. -Xmx only controls the heap. Outside it, Java also uses memory for plugin code, threads, network buffers and the cleanup itself - and all of that has to fit inside your plan's limit too.

A workable rule of thumb is to leave around 15%, or at least 1 GB, free:

Your plan	Set -Xmx to
2 GB	1500M
4 GB	3G
6 GB	5G
8 GB	6500M
12 GB	10G
16 GB	13G

A side effect to know about: with -Xms and -Xmx equal, the server claims the whole amount immediately. Your panel's memory graph therefore sits near 100% all the time. That is normal and not a leak.

Aikar's flags are the recommended setup for Java's memory cleanup on Minecraft. The current string lives at docs.papermc.io/paper/aikars-flags.

Aikar's flags do not fix an OOM. They change how memory is cleaned up, not how much exists. If you are short on RAM, they help nothing.

---

Is it too little RAM, or a leak?

Do not look at the top of the curve - it always sits close to -Xmx. Look at how far it drops after a cleanup:

	Too little RAM	A leak
The bottom of the curve	Flat - falls back to the same level every time	Rising - a little higher each time
When it happens	With many players, or during pregeneration	After many hours of uptime, often at night with nobody on
Does a restart help?	Only until the load returns	Yes - for roughly the same number of hours every time

"A restart fixes it for about the same number of hours every time" is the strongest sign of a leak.

Measure it with spark, which is bundled with Paper from 1.21:

/spark health
/spark gc
/spark heapsummary --run-gc-before

• /spark gc shows how often and how long cleanup runs. Constant back-to-back collections mean the heap is saturated.
• /spark heapsummary --run-gc-before shows what is actually taking up the space.

--run-gc-before is not optional. Without it, rubbish that simply has not been cleared yet is counted too - and then everything looks like a leak. Take two measurements an hour apart and compare: whatever grew is your culprit.

---

The usual causes on a Minecraft server

1. Too many loaded chunks. The single most common cause. A running pregeneration loads chunks faster than they can be cleared - which is why servers often die at night with not a single player online.
2. Accumulated entities and items. Mob farms and piles of dropped items. One AFK farm can keep tens of thousands of entities alive.
3. Too high a view-distance. Memory rises roughly with the square: from 10 to 16 is not 60% more, it is about 2.5 times as much.
4. A plugin with a leak. Typically map and render plugins during a full render, or plugins that store per-player data without ever clearing it.
5. Large modpacks. 200+ mods genuinely need 6-10 GB and cannot be tuned down to 2.
6. Too many worlds loaded. Every world keeps its spawn chunks in memory permanently, whether or not anyone is in it. Unloading unused worlds is often the easiest win of all.

---

Java version

The wrong Java version does not give you a memory error - it gives you UnsupportedClassVersionError. But check it while you are here:

Minecraft version	Java
1.17 - 1.19	Java 17
1.20 - 1.21.11	Java 21
26.1 and newer	Java 25

Note that Minecraft moved to a year-based version number in 2026. 26.1 is newer than 1.21, even though the number looks smaller.

---

What to do, in order

1. Work out which kind of error it is from the table at the top. Everything else depends on it.
2. Check the allocation is sane. Is -Xms equal to -Xmx, and is there at least 1 GB of headroom under the plan? About half of all cases end here.
3. Measure instead of guessing. /spark health and /spark gc.
4. Decide leak or capacity with the floor test above.
5. If it is capacity: cut load first. Lower view-distance and simulation-distance, stop any pregeneration, unload unused worlds, tighten mob limits. Only then buy more RAM.
6. If it is a leak: find the plugin with two heapsummary measurements, then update or remove it. Stop using /reload.
7. Turn on diagnostics for next time with -XX:+HeapDumpOnOutOfMemoryError, so you have something to look at.

---

What not to do

• Do not give Java your whole plan. That is the direct route to exit code 137.
• Do not raise -Xmx on exit code 137. It makes the error more frequent, not less.
• Do not disable the watchdog with max-tick-time=-1. You hide the symptom and get a server that hangs instead of restarting.
• Do not expect Aikar's flags to give you more memory. They give smoother ticks, not more room.
• Do not use /reload when swapping plugins. It is the direct cause of Metaspace errors.

Cannot read your spark report or your log? Send us the link or logs/latest.log in a ticket and we will look at it with you.