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.
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.
- 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. - When the crash happens. Note whether it happens right after start, at a load peak, or only after hours of running.
- 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.
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
- Open the command or service definition that starts the application. You change the limit there because
-Xmxis read only at JVM start. - Set
-Xmxto 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. - 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.
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
- 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.
- Open the dump in a heap analyzer from your JVM vendor's documentation.
- Sort object types by retained size. The types that hold the most memory are your suspects.
- 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.
- 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
- 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.
- 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.
- 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.
- 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. - 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.
- 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.
- Replay the same load that caused the crash, for at least as long as it took to fail before.
- Check the log again for the error text.
- Watch heap usage over the whole run. It should rise and fall with load and return to a stable floor.
- 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.
grep -c "OutOfMemoryError" YOUR_APP.log
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| The error returns after you raise -Xmx, only later than before | The 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 effect | The 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 job | The 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 occurs | The 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 -Xmx | The 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







