Skip to content

Grokem · https://www.grokem.com/programming/fix-java-heap-space-outofmemoryerror-and-find-the-memory-leak-in-your-jvm-app

ProgrammingTroubleshooting guide

Fix Java heap space OutOfMemoryError and find the memory leak in your JVM app

Work through the causes of OutOfMemoryError: Java heap space in order of probability: a heap limit that is too low, a leak or wasteful usage, and engines running in local mode. Each fix comes with a way to confirm it worked.

Krishna Sharma

Technical Writer

Published Updated
  • 6 min read
  • 0 sec

Tested with
  • Java Virtual Machine (JVM)
  • -Xmx option
Your progress
  1. Fix Java heap space OutOfMemoryError and find the memory leak in your JVM app6 min(finished)
    0%

Your application stops with java.lang.OutOfMemoryError: Java heap space, often under what you consider normal load. The JVM could not find enough free heap for a new object, even after trying to reclaim memory.

You have two broad options: raise the maximum heap size with -Xmx, or optimise the application's memory usage. This guide orders the likely causes by probability, gives the fix for each and shows how to confirm it worked.

No JVM version is pinned here. Option names and tooling can differ between JVM vendors and releases, so check your vendor's documentation for anything not named below.

Recognise the symptom

Look for this text in your log:

java.lang.OutOfMemoryError: Java heap space

The words after OutOfMemoryError: matter. This guide covers only the heap space variant. If your message ends differently, jump to the section on errors that are not heap problems.

Find the first occurrence, not the last. Later errors are often side effects of the first failure.

bash
grep -n "OutOfMemoryError" YOUR_APP.log

Collect three facts before you change anything

Record these before you touch a setting. They tell you which cause to chase.

  1. The current maximum heap. Check the start command for -Xmx. If it is absent, the JVM is using a default you have not chosen. Note that value in your monitoring or startup log.
  2. When the crash happens. Note whether it happens right after start, at a load peak, or only after hours of running.
  3. How heap usage behaves. Note whether usage drops back after memory is reclaimed, or whether the floor keeps rising.

The pattern decides the path. A crash at a load peak with a flat floor points to a limit that is too low. A floor that rises over time points to a leak or to data that is kept longer than needed.

OutOfMemoryError:Java heap spacein logHeap floorrises overtime?Local modeSpark or Hail?Raise -Xmxand restartHeap dump,find retainedobjects,fix codeSet memory attop of scriptReplayload andcheck logNoYes
Pick the fix path from how heap usage behaves.

Cause 1 (most likely): the heap limit is too low for the workload

Start here. The most direct fix for the error is to increase the maximum heap size allocated to the JVM. This is the cheapest test, and it tells you whether the application simply needs more memory.

Fix

  1. Open the command or service definition that starts the application. You change the limit there because -Xmx is read only at JVM start.
  2. Set -Xmx to a larger value than the current one. Raise it in a measured step, not to the full memory of the machine, so the operating system keeps room for everything else.
  3. Restart the application. The new limit applies only to a new JVM process.

The example uses 2g as an illustration. Choose a value that fits your host.

bash
java -Xmx2g -jar YOUR_APP.jar

Cause 2: a memory leak or wasteful memory usage

If a larger heap only delays the crash, you are not short of memory. You are holding on to it. A bigger -Xmx then just moves the failure later.

Signs

  • The crash time moves later when you raise -Xmx, but it still arrives.
  • Heap usage after memory is reclaimed climbs over time.
  • The error appears after long uptime, not at start.

Find the leak

  1. Capture a heap dump close to the failure. A heap dump is a snapshot of every live object. The exact option or tool depends on your JVM vendor, and it is not covered here, so check your vendor's official documentation.
  2. Open the dump in a heap analyzer from your JVM vendor's documentation.
  3. Sort object types by retained size. The types that hold the most memory are your suspects.
  4. Follow the references from the largest group back to the object that keeps it alive. This is usually a long-lived collection, a cache with no size limit, or a static field.
  5. Compare two dumps taken at different times if you can. A type whose count grows between them is the leak.

Fix

Fix the code that holds the references. Typical changes are to bound a cache, remove entries when they are no longer needed, or stop loading a whole data set into memory when you can process it in pieces. Optimising memory usage is the second fix the error calls for, next to raising the heap.

Cause 3: an engine running in local mode

If you installed Hail or Spark with pip, you are running in local mode. The engine then runs inside a single JVM on your machine, and that JVM's heap limit applies to all of the work. A job that would fit on a cluster can fail with the same heap error.

Fix

  1. Check how the engine is started at the top of your script. The Hail guidance for this error says to add a setting at the top of your script, and the exact setting is not reproduced here.
  2. Read the current Hail or Spark documentation for that setting and apply it before the engine starts. Settings applied after start have no effect on an already running JVM.
  3. Re-run the job and watch for the error.

If the data truly does not fit in one machine's memory, move the job to a cluster instead of raising the limit again.

Cause 4: the failure is not a heap space problem

Some reports describe random out of memory errors where heap, system load and other metrics show no increase when the error occurs. If you see that pattern, do not keep raising -Xmx.

  1. Re-read the full error text. Confirm it says Java heap space. A different message names a different memory area, and a larger heap will not fix it.
  2. Check whether the error comes from a launched application, such as a game client, rather than your own service. In that case the heap setting is usually in that application's launcher, not in your start script.
  3. Check your monitoring interval. A short spike can fall between samples and make the heap look flat.

This guide does not cover the other memory areas. Use your JVM vendor's official documentation for those messages.

Confirm the fix worked

Do not declare success because the application started.

  1. Replay the same load that caused the crash, for at least as long as it took to fail before.
  2. Check the log again for the error text.
  3. Watch heap usage over the whole run. It should rise and fall with load and return to a stable floor.
  4. If the floor still rises, the larger heap has only delayed a leak. Go back to cause 2.

Repeat the run once more after the next deployment. A fix you verified only once may hide a slow leak.

bash
grep -c "OutOfMemoryError" YOUR_APP.log

Troubleshooting

ProblemLikely causeFix
The error returns after you raise -Xmx, only later than beforeThe application holds references to objects it no longer needs, so a bigger heap only delays the failure.Capture a heap dump near the failure, find the largest retained types in a heap analyzer and fix the code that keeps them alive.
The new -Xmx value seems to have no effectThe option was added to a command that is not the one that starts the process, or the process was not restarted.Edit the actual start command or service definition, restart the application and check the startup command of the running process.
The error appears in a pip-installed Spark or Hail jobThe engine runs in local mode inside one JVM with a limited heap.Apply the memory setting at the top of your script before the engine starts, as the Hail documentation describes, or move the job to a cluster.
Heap and load look normal when the error occursThe error may not be a heap space error, or your monitoring interval is too coarse to catch a short spike.Confirm the exact message text and shorten the monitoring interval during a replay.
The host becomes slow after you raise -XmxThe heap limit is too close to the memory of the machine, leaving little for the operating system and other processes.Lower -Xmx to a value that leaves headroom and fix memory usage in the application.

Frequently asked questions

Should I raise -Xmx or fix the code?

Do both in order. Raising the maximum heap is the quick test and the direct fix if the workload simply needs more memory. If the error returns later, optimise memory usage and look for a leak.

How do I know it is a leak and not a small heap?

Watch heap usage after memory is reclaimed. If the floor keeps rising over time, or a larger heap only delays the crash, you have a leak or data kept too long.

Why does my pip-installed Spark or Hail job hit this error?

A pip install means local mode, where everything runs in one JVM with its own heap limit. Set the memory option at the top of your script, as the Hail guidance describes.

What if the error appears at random and heap does not grow?

Confirm the message really says Java heap space and check your monitoring interval. A different message points to a different memory area.

Which tool should I use to take a heap dump?

The option and tool depend on your JVM vendor. Check the vendor's official documentation.

From Grokem: https://www.grokem.com/programming/fix-java-heap-space-outofmemoryerror-and-find-the-memory-leak-in-your-jvm-app

Finished this article?

How did this strike you?

Be the first to react – it is anonymous.

Community

Questions about this?

Ask in Questions and help and get help from other readers.

Ask a questionBrowse Questions and help

Comments

No comments yet. Share what worked for you, or ask a question.

Keep learning

Picked for this article

Related reading, discussions and learning paths on the same subject.

All in Programming

Choose what we may use. You can change this at any time with “Privacy choices” at the foot of every page. Details are in the Cookie policy and the Privacy policy.

Strictly necessary

Remembers your theme, the lessons you marked as done and this choice. It stays on your device, tracks nothing and cannot be switched off.

Always on
What exactly is collected, and why

Google Analytics

Collects
The pages you view, your device and browser type, your language, how you reached the site and your approximate location (country and city, worked out from your IP address).
Why
To understand which pages and lessons are used, so we can improve them.
Stored
Two cookies, _ga and _ga_<id>, for up to 2 years. Google acts for us; the data is processed by Google, including outside your country.

Grokem’s own counts

Collects
The pages you open and how long you stay, how far you scroll, where you came from, your device type, browser, screen size, language and time zone. Your IP address is turned into a code that changes every day; it is never stored as it is.
Why
To see how long lessons are read and where readers leave. Not shared with anyone.
Stored
A random visitor ID, a visit ID and the time of your last page view in your browser’s storage (gr_vid, gr_sid, gr_last). No name or email is attached.