Minecraft Server Out of Memory: Heap Errors, Limits and Leaks

Start with the exact error when a Minecraft server runs out of memory. A Java heap-space exception means the JVM could not satisfy a heap allocation; a container or host OOM kill means an external memory boundary was reached. Those failures can need different fixes. Raising the heap to the full hosting limit can make an external kill more likely.

Which failure did you actually see?

Preserve the complete log and timestamp
Evidence	What it suggests	Next check
Java heap-space error	Heap allocation failed	Configured Xmx, retained objects and workload at failure
Native-thread/direct-buffer allocation error	Memory or limits outside ordinary heap allocation	Thread count, native overhead and process limits
OOMKilled or host OOM event	A system/container memory boundary was enforced	Actual limit, total charged usage and other processes
Exit code 137 alone	Termination by SIGKILL in common Unix conventions	Panel/host event; this code alone does not prove OOM
Long pauses without an OOM event	Another performance symptom	GC, tick profile, I/O and scheduling evidence

1. Save evidence before restarting repeatedly

Save the final server log, crash report and panel event with UTC time.
Record the startup command, Java version, heap cap and total service limit.
Note player activity, recently changed mods/plugins and any scheduled backup or generation job.
If you administer the OS, inspect its service and kernel logs for termination evidence. Ask the host for the relevant event if you do not have that access.

Do not publish a heap dump or full environment dump casually. It can contain player data, credentials or application secrets, and creating one may need substantial free disk space. Use a protected diagnostic workflow with a clear retention plan.

2. Compare heap with total process usage

Java needs memory outside its managed heap. A game container may also charge other processes or file-backed usage under its configured policy. Identify what the provider’s limit measures before deciding that the graph contradicts the JVM. On a VPS, leave resources for the OS and every colocated service.

Use the Minecraft RAM guide for allocation planning and VPS memory checks when the operating system is under your control. An arbitrary larger Xmx value is not a substitute for this comparison.

3. Distinguish a workload peak from retained growth

An allocation graph rising between garbage collections is normal behavior, not sufficient evidence of a leak. Compare post-collection usage under similar activity and over a useful interval. A pack that loads many dimensions may have a different steady state from an idle lobby. Look for retained growth that continues after the original activity stops.

If the failure followed an extension update, reproduce it on a protected copy with the recorded versions. Change one variable and preserve the results. Removing a content mod directly from the only production world can damage saved data and still fail to establish the original cause.

4. Apply a fix that matches the evidence

For insufficient heap with total headroom, adjust through the supported startup controls and retest.
For external kills, reduce the heap or competing usage, or increase the actual service limit where justified.
For runaway retained data, investigate the responsible workload or extension rather than scheduling endless restarts as the only remedy.
Verify startup, busy play, a clean restart and backup creation after the change.

Compare Minecraft hosting resources when the measured working set needs a larger allocation. Keep the evidence with the decision so later updates can be checked against the same baseline.