java.lang.OutOfMemoryError on a Minecraft server: the five kinds, and what fixes each one
OutOfMemoryError is not one error. The words after the colon name which pool of memory ran out, and the fix is different for each: two of them are a flag, not more RAM. A server that dies with no Java error at all and an exit code of 137 is the fifth kind, and the one most often misread.
Read the words after the colon
A Java process has several separate memory pools, each with its own ceiling. The heap holds the world, the entities and every object the game creates. Metaspace holds the loaded classes — every mod's code. Direct buffers hold network and file I/O. The container the server runs in has a ceiling over all of them together. Running out of any one of these produces a differently worded error, and raising the wrong ceiling does nothing.
| What the log says | Which pool | What it usually means |
|---|---|---|
| OutOfMemoryError: Java heap space | Heap | The world and the mods' objects do not fit in the heap. Too many loaded chunks, too many entities, or a pack that needs more memory than the server has. |
| OutOfMemoryError: GC overhead limit exceeded | Heap | The same problem one step earlier: the garbage collector is spending nearly all its time reclaiming almost nothing. |
| OutOfMemoryError: Metaspace, or Compressed class space | Class metadata | The mods' classes do not fit in the metaspace cap. Seen during mod loading on big packs, before the world opens. |
| OutOfMemoryError: Direct buffer memory, often with Cannot reserve N bytes of direct buffer memory | Direct (off-heap) buffers | Networking or chunk I/O outgrew the direct-memory cap. A flag-sized problem, not a RAM-sized one. |
| No Java error at all; the process just ends, exit code 137, sometimes a bare Killed | The whole container | The operating system killed the JVM for exceeding the container's memory limit. The heap plus everything off-heap overran the box. |
Heap: Java heap space and GC overhead
The heap runs out when the live world outgrows it. The levers are the amount of world kept loaded and the memory the server has to hold it. view-distance in server.properties is the big one: the number of loaded chunks grows with the square of the distance, so dropping from 12 to 8 roughly halves the chunks in memory. simulation-distance, where the server has one, controls how many of those chunks tick, which is what drives entity and block-entity load.
If the distances are already modest and the heap still fills, the pack wants more memory than the server has. That is not a flag problem. Raising -Xmx past the container's actual limit turns a clean Java error into the exit-137 kill above; it does not create memory.
How much a pack actually wants depends on the pack and the player count. Size it before you buy or upgrade rather than guessing from the error.
Open the RAM calculatorMetaspace: the mods' classes do not fit
Metaspace is sized by a JVM flag, -XX:MaxMetaspaceSize, not by the amount of RAM on the server. A large pack loads a great many classes during mod construction, and if the cap is too small for the mod count it dies there — usually in the loader's construction phase, before any world exists. The fix is to raise that cap, and because the total is bounded by the container, to take the extra back out of the heap so the two together still fit.
Direct buffer memory: a flag, not more RAM
Direct buffers are off-heap memory the networking layer and chunk I/O use, capped by -XX:MaxDirectMemorySize. A small default cap against a busy modded server produces Cannot reserve N bytes of direct buffer memory with the allocated and limit figures printed on the line. Raise the cap, trade it out of the heap, and the error goes away. Adding RAM without touching the flag does not.
Exit 137: the container limit, not the JVM
The JVM's own ceilings are all inside the container's ceiling. The heap, the metaspace, the direct buffers, the code cache, thread stacks and the garbage collector's bookkeeping all add up, and when the sum crosses the container limit the kernel ends the process without a Java error. The usual cause is a heap sized to the whole box with nothing left over for everything else — which is why a heap that is a little smaller than the RAM is the correct setting, not a waste.
How to fix it
- Identify the kind from the table above. Everything below depends on it.
- Heap or exit 137: lower view-distance by a few chunks and simulation-distance by one or two, restart, and watch whether it recurs under the same player load.
- Heap or exit 137 again: the pack needs more memory than the server has. Move to a plan with more RAM, or trim the pack.
- Metaspace: raise -XX:MaxMetaspaceSize and reduce -Xmx by the same amount so heap plus off-heap still fits the box.
- Direct buffer memory: raise -XX:MaxDirectMemorySize the same way. The number on the error line tells you the current cap.
- In every case, check the pack's own recommended memory before assuming a bug. A pack that says 8 GB and is running in 4 GB is not misbehaving.
What MineXHost's launcher does with this crash
MineXEngine sizes the JVM from the real memory limit of your server's container, not from a number you type. The heap is set to what is left after the off-heap caps for your pack's mod count, so heap plus off-heap stays inside the limit and the exit-137 kill does not come from the flags. The heap is allowed to start small and grow, so an idle server does not hold memory it is not using.
On a Metaspace or Direct-buffer error, the engine raises the relevant cap — by half again, and at least 256 MB — and takes the same amount back out of the heap, then restarts and prints the old and new figures in your console. It does this once per cap. If the same error comes back after the retune, it says so plainly: the pack needs more memory than the plan has.
On a heap error or a kernel kill, the engine makes one recovery attempt: it lowers view-distance by four and simulation-distance by two in server.properties, neither below four, removes rotated log files, and restarts. That is a change to your server.properties, and it is logged in the console as it happens. A second heap error after that is reported as needing more RAM rather than retried, because a smaller world was the only lever the engine will pull on its own.
Moving to a plan with more memory is a plan change in your account. The server keeps its files and its world and is resized to the new plan, with the new memory limit taking effect on its next restart — there is no reinstall and no world transfer involved.
MineXHost runs large Forge, NeoForge and Fabric packs on MineXEngine — our launcher auto-detects the modpack, picks the right Minecraft loader and Java version, tunes the JVM for your RAM, and auto-recovers from the crashes that normally end a modded server's evening. Pick your RAM, paste the pack, and play.
See hosting plansFrequently asked questions
What does “java.lang.OutOfMemoryError: Java heap space” mean on a Minecraft server?
Java heap space means the server's live world — loaded chunks, entities and every object the mods keep — no longer fits in the heap the JVM was given, so the game cannot allocate the next object and stops. The levers are how much world is loaded and how much memory the server has: lower view-distance, which shrinks loaded chunks with the square of the distance, and if it recurs under normal load the pack needs more RAM than the server has. Raising -Xmx past the machine's real limit does not help.
What is exit code 137 on a Minecraft server?
Exit code 137 means the process was killed with SIGKILL, which on a memory-limited server is the operating system's out-of-memory killer ending the JVM because heap plus everything off-heap exceeded the container's limit. Java prints nothing, so the log simply stops. It is the same underlying problem as a heap error one step later, and the usual cause is a heap sized to the whole box with no margin for classes, buffers and the collector's bookkeeping. Leave headroom, or move to more RAM.
How do I fix “OutOfMemoryError: Metaspace” on a Forge server?
A Metaspace error means the classes loaded by your mods do not fit in the metaspace cap set by the -XX:MaxMetaspaceSize flag, which is independent of how much RAM the server has. Raise that flag and reduce -Xmx by the same amount so the heap and the metaspace together still fit inside the server's memory. It typically strikes during mod construction on large packs, before any world loads. On MineXHost the launcher raises the cap and rebalances the heap automatically on the first occurrence.
What does “Cannot reserve bytes of direct buffer memory” mean?
The direct-buffer error means the off-heap memory used by networking and chunk I/O hit the -XX:MaxDirectMemorySize cap, and the line prints the bytes requested, the bytes already allocated and the limit. It is fixed by raising that flag and taking the extra out of the heap, not by adding RAM — a server with plenty of memory and a small direct cap fails exactly the same way. On MineXHost the launcher raises the cap once and restarts; if the error persists it reports the pack needs more memory.
Will MineXHost change my server settings after an out-of-memory crash?
After a heap error or a kernel kill, MineXEngine makes one recovery attempt that does edit server.properties: it lowers view-distance by four and simulation-distance by two, never below four, removes rotated log files, and restarts, and it prints each change in your console. After a Metaspace or Direct-buffer error it changes JVM flags instead and leaves server.properties alone. A second crash of the same kind is reported as needing more RAM rather than retried, and moving to a larger plan resizes the server in place, keeping its world, with the new limit applied on the next restart.