Search guides

Fix Java that runs out of memory

We'll confirm the error, increase heap with -Xmx, check for leaks—or tell you when to escalate.

Troubleshooting · Devices & software
15–30 min
What you'll need
  • Access to JVM startup options (script, systemd, IDE)
  • Optional: profiler (Eclipse MAT, VisualVM) for heap analysis
Step 1 of 7

Quick triage — pick your path

Get started

Choose the option that matches what you see. You can jump straight to that section.

Show full guide

Steps

Goal: Confirm the error, increase heap with -Xmx, check for leaks.

Check heap and increase -Xmx

Goal: See current heap limit and increase it.

  • Check how the JVM is started. Look for -Xmx in the script, systemd unit, or IDE. Run java -XX:+PrintFlagsFinal -version 2>&1 | grep MaxHeapSize to see default.
  • Add -Xmx<size> to the JVM options. Examples: -Xmx2g, -Xmx4096m. Use -Xms2g -Xmx2g for fixed heap. Restart the JVM.
  • When the app runs in Docker or systemd, check container memory limits. -Xmx must fit within the limit.
  • Good: New -Xmx set and JVM restarted. Monitor for OOM.
  • Bad: OOM continues—see Analyze with heap dump.

Analyze with heap dump

Goal: Capture a heap dump on OOM and analyze for leaks.

  • Add -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/path/to/dump.hprof to JVM options. Reproduce the OOM. The JVM writes a .hprof file.
  • Open the dump in Eclipse MAT or VisualVM. Look for retained objects and memory leaks.
  • When a leak is found, fix the application code or upgrade the library.
  • Good: Dump captured and analyzed. Fix applied or -Xmx increased.
  • Bad: OOM continues at max -Xmx—see When to escalate.

When to escalate

When to get help: Escalate if:

  • OOM continues after increasing -Xmx to the system limit.
  • You need a heap dump analyzed.
  • The app has a known leak that requires code changes.

Provide -Xmx value, full OutOfMemoryError, and heap dump path before escalating.

Verification

  • The JVM runs without OutOfMemoryError under normal load.
  • -Xmx is set and visible in the process or startup logs.
  • Heap usage is stable or within limits when monitored.

Escalation ladder

Work from the device outward. Stop when the problem is fixed.

  1. Increase -Xmx Add -Xmx2g (or appropriate size) to JVM options.
  2. Heap dump Add -XX:+HeapDumpOnOutOfMemoryError; analyze with MAT or VisualVM.
  3. Check for leak Monitor heap over time; restart and observe.
  4. Tune GC Try G1GC or adjust MaxGCPauseMillis.
  5. Escalate Provide -Xmx, error, heap dump; add RAM or fix app.

What to capture if you need help

Before calling support or posting for help, have these ready. It speeds everything up.

  • Full [OutOfMemoryError](#term-outofmemoryerror) message
  • Current -Xmx and -Xms values
  • Heap dump path (if generated)
  • Steps already tried

Do you see OutOfMemoryError?

Check logs or console. OutOfMemoryError: Java heap space or GC overhead limit.

Check the logs. OutOfMemoryError: note "Java heap space" or "GC overhead limit exceeded". Other error: check the exact message. Confirm you should see OutOfMemoryError and type.

Yes No

You can change your answer later.

Check the exact error

If not OutOfMemoryError, the issue may be different. Native OOM, stack overflow, or permgen (old Java) have different fixes. Check the full stack trace.

Done

What is the current -Xmx setting?

Check JVM startup options or run -XX:+PrintFlagsFinal -version.

Check how the app is started. Look for -Xmx in the script, systemd unit, or IDE run config. Run `java -XX:+PrintFlagsFinal -version 2>&1 | grep MaxHeapSize` to see default. Low or absent: increase \-Xmx. Already high: check for leak. Confirm you should see current heap limit.

Yes No (already high)

You can change your answer later.

Increase -Xmx and restart

Add `-Xmx2g` (or appropriate size) to JVM options. Use `-Xms2g -Xmx2g` for fixed heap. Restart the JVM. Confirm you should see the new limit and no OOM under normal load.

Done

Does heap grow until OOM without leveling off?

Monitor with jstat -gc <pid> or a profiler.

Restart the app. Monitor heap with `jstat -gc <pid> 1000` or a profiler. Grows until OOM: likely leak—add -XX:+HeapDumpOnOutOfMemoryError, get dump, analyze. Stable then spike: may need more -Xmx or tune GC. Confirm you should see heap behavior over time.

Yes No

You can change your answer later.

Add heap dump and analyze

Add `-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/path/to/dump.hprof`. Reproduce OOM. Analyze the .hprof with Eclipse MAT or VisualVM. Look for retained objects. Confirm you should see the dump and identify the leak.

Done

Escalate

Provide -Xmx value, full OutOfMemoryError, heap dump path if available. Escalate if OOM continues at max -Xmx, or you need to add RAM. See fix-out-of-memory-error-on-server for system-level OOM.

Done

Reviewed by Blackbox Atlas

Frequently asked questions

What causes Java OutOfMemoryError?
The [heap](#term-heap) is exhausted. Too little -Xmx, a memory leak, or a spike in allocation. Increase -Xmx first; then check for leaks.
How do I increase Java heap size?
Add -Xmx<size> to the JVM options. Example: -Xmx2g or -Xmx4096m. Set -Xms to match -Xmx for fixed heap. Restart the JVM after changing.
When should I escalate Java OOM?
If -Xmx is already high and OOM continues, or you need a heap dump analyzed. Provide -Xmx value, error message, and heap dump if available.

Rate this guide

Was this helpful?

Continue to