java.lang.OutOfMemoryError: Java heap space

The exact error string

Exception in thread "main" java.lang.OutOfMemoryError: Java heap space
        at java.base/java.util.Arrays.copyOf(Arrays.java:3512)
        at java.base/java.lang.AbstractStringBuilder.ensureCapacity(AbstractStringBuilder.java:239)
        at com.example.ReportBuilder.build(ReportBuilder.java:88)
        at com.example.Main.main(Main.java:24)

An important thing to understand up front: the stack trace shows where memory ran out, not what caused it. The frame at the top is simply the unlucky allocation that happened to be the last straw — often something innocuous like growing a StringBuilder or copying an array. The objects actually filling the heap were usually allocated somewhere else entirely, possibly minutes earlier. Chasing the line in the stack trace is the single most common wasted afternoon with this error.

Step 1: leak, or just too small?

Everything downstream depends on this one question, and it has a precise answer. Watch what happens to heap usage after each full garbage collection — the low points, not the peaks:

# log every GC with heap before/after — the cheapest way to see the baseline
java -Xlog:gc* -jar app.jar

# JDK 8 equivalent
java -XX:+PrintGCDetails -XX:+PrintGCDateStamps -jar app.jar

# live view of a running process
jcmd <pid> GC.heap_info
jstat -gcutil <pid> 5s

Fix 1: the heap is genuinely too small

If the baseline is flat and the application simply needs more room at peak load, raising the maximum heap is the right and complete fix:

java -Xms1g -Xmx2g -jar app.jar

Setting -Xms (initial) equal to -Xmx (maximum) is common for servers: it avoids the cost of growing the heap incrementally and makes memory behaviour predictable from the first request. The trade-off is that the process reserves that much up front.

Be aware that a bigger heap is not free. Full-GC pauses scale with heap size, so a very large heap can turn a memory problem into a latency problem. If you're pushing past a few gigabytes, it's usually worth switching collectors (G1 is the default on modern JDKs; ZGC or Shenandoah for low-pause requirements) rather than just growing the number.

Fix 2: it's a leak — find what's retaining memory

If the baseline climbs, no -Xmx value will save you; it just moves the crash later. Capture a heap dump and find what's holding the objects alive:

# write a dump automatically when it fails — set this in production ahead of time
java -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp -jar app.jar

# or take one on demand from a running process (live = after a full GC)
jmap -dump:live,format=b,file=heap.hprof <pid>

Open the .hprof in Eclipse MAT (the standard tool) or VisualVM and run the Leak Suspects report. The critical view is the dominator tree: it doesn't just show which objects are biggest, it shows the reference chain keeping them alive — which is the actual answer to "why isn't this being collected?"

The recurring culprits, roughly in order of how often they turn up:

Fix 3: one huge allocation — stream instead of loading

Sometimes there's no leak and the heap isn't unreasonably small: a single operation just tries to materialise something enormous. Reading a large file, or a query with no LIMIT, into a list is the usual shape:

// ❌ entire file in memory at once
List<String> lines = Files.readAllLines(Path.of("huge.log"));

// ✅ stream it — one line in memory at a time
try (Stream<String> lines = Files.lines(Path.of("huge.log"))) {
    lines.filter(l -> l.contains("ERROR")).forEach(this::handle);
}

// ❌ unbounded result set — the whole table lands in a List in memory
List<Row> all = jdbc.query("SELECT * FROM events", rowMapper);

// ✅ page with LIMIT/OFFSET (or a keyset), or stream with a real server-side cursor
jdbc.setFetchSize(1000);

setFetchSize is a hint, not a guarantee — most drivers happily ignore it and buffer the full result set anyway unless additional conditions are met. On PostgreSQL it only takes effect with auto-commit off (connection.setAutoCommit(false)); on MySQL the driver requires useCursorFetch=true in the connection URL, or a MySQL-specific streaming mode via Statement.setFetchSize(Integer.MIN_VALUE), which has its own restrictions (e.g. you must read the whole result set before issuing another query on that connection). Check your driver's own documentation before assuming setFetchSize alone keeps a large query off the heap — the safer bet for genuinely huge result sets is explicit paging (LIMIT/OFFSET or a keyset) at the query level.

The same trap applies to parsing a large JSON document with a tree-based parser: the whole object graph lands on the heap at once. Streaming parsers (Jackson's JsonParser, or Gson's JsonReader) process it incrementally instead. If you're working out the shape of a large payload before deciding how to parse it, our JSON Formatter is a quick way to inspect its structure without writing throwaway code — and the equivalent decode problems in Go follow the same "decode into a typed target, don't hold it all" principle.

Fix 4: sizing the heap inside a container

This deserves its own treatment, because the failure mode is different and confusing. In Docker or Kubernetes there are two ceilings: the JVM's -Xmx, and the container's memory limit enforced by the kernel. Which one you hit determines what you see:

The second case surprises people because there's no Java error to read — the process simply vanishes. It happens when -Xmx is set close to the container limit, leaving no headroom for everything that lives outside the heap: thread stacks, metaspace, the JIT code cache, GC structures, and native/direct buffers. Those can easily add several hundred megabytes.

# ❌ container limit 512m, heap allowed 512m — no room for non-heap memory
docker run -m 512m myapp java -Xmx512m -jar app.jar

# ✅ let the JVM size itself from the container limit, with headroom
docker run -m 512m myapp java -XX:MaxRAMPercentage=75.0 -jar app.jar

Modern JDKs (10+) are container-aware by default — UseContainerSupport is on, so the JVM reads the cgroup limit rather than the host's total RAM. -XX:MaxRAMPercentage is therefore the better flag in containers: it scales automatically when you change the limit, instead of silently becoming wrong the next time someone edits the deployment.

The container-aware default is 25%, which is lower than most people expect

"Container-aware" is easy to read as "sized sensibly to the limit." The number is worth knowing exactly, because it is conservative: with no heap flags at all, the default MaxRAMPercentage is 25.0, so three quarters of the container's memory is left unused by the heap. Measured on eclipse-temurin:21-jre-alpine:

$ docker run --rm --memory=<LIMIT> eclipse-temurin:21-jre-alpine \
    java -XX:+PrintFlagsFinal -version | grep -E 'MaxHeapSize|MaxRAMPercentage'

--memory=512m  →  MaxHeapSize = 128 MB   MaxRAMPercentage = 25.0
--memory=1g    →  MaxHeapSize = 256 MB   MaxRAMPercentage = 25.0
--memory=2g    →  MaxHeapSize = 512 MB   MaxRAMPercentage = 25.0

bool UseContainerSupport = true {product} {default}

That cuts both ways. It is why a service can throw OutOfMemoryError: Java heap space in a 2 GB container while docker stats shows it using well under a gigabyte — the heap ceiling was 512 MB and the other 1.5 GB was never available to it. If that is your situation, the heap is not "genuinely too small" in the sense of Fix 1; it is being capped at a quarter of what you provisioned, and raising MaxRAMPercentage is the fix rather than enlarging the container.

One caution in the other direction, which is the real reason this flag is not just "set it to 90". An explicit -Xmx overrides container awareness — UseContainerSupport supplies the default, it does not cap a value you asked for. A JVM given -Xmx512m inside a 128 MB container reports maxMemory=494MB, happily allocates past the cgroup limit, and is killed by the kernel mid-allocation:

# heap under the limit  → the JVM throws, and you get a stack trace to read
--memory=256m, -Xmx64m  :  maxMemory=61MB   →  java.lang.OutOfMemoryError: Java heap space
                                               ExitCode=0   OOMKilled=false

# heap over the limit    → killed before it can diagnose itself, no Java output at all
--memory=128m, -Xmx512m :  maxMemory=494MB  →  (nothing)
                                               ExitCode=137 OOMKilled=true

This gives you a clean way to tell the two ceilings apart after the fact, which is the practical version of the table above: if you have a Java stack trace, the JVM stayed inside its own limit and you are on the right page. If the container died with no Java output at all, -Xmx was larger than the container limit — the absence of a stack trace is the diagnosis, not missing logs, and exit code 137 / OOMKilled covers it.

You cannot fill -Xmx with live data

One more measured number, because it affects how you size from a known working set. Retaining 1 MB blocks in an ArrayList under -Xmx32m died after 14 MB — under half the heap:

$ java -Xmx32m Oom.java
max heap = 32 MB
caught: java.lang.OutOfMemoryError: Java heap space
retained 14 MB before dying

The rest went to GC headroom (a collector needs somewhere to copy survivors to) and to the growing list's own backing array, which must briefly hold both the old and new copy while it doubles. So if you know your live set is 600 MB, -Xmx600m will not run — budget meaningfully above the working set rather than at it.

Measured on Java 21.0.11 (OpenJDK 64-Bit Server VM, build 21.0.11+9-LTS-211), container figures on eclipse-temurin:21-jre-alpine under Docker 25.0.2. The 25 % default and UseContainerSupport have been stable since JDK 10, but both are tunable, so read them off your own runtime with -XX:+PrintFlagsFinal rather than assuming.

Related OutOfMemoryError variants

The message after OutOfMemoryError: tells you which region ran out, and they have different fixes:

Debugging checklist

• ✓ Ignore the stack trace's top frame — it's the last straw, not the cause
• ✓ Enable -Xlog:gc* and compare post-GC low points over time
• ✓ Flat baseline → undersized heap; raise -Xmx (Fix 1)
• ✓ Rising baseline → leak; take a heap dump and read the dominator tree (Fix 2)
• ✓ Set -XX:+HeapDumpOnOutOfMemoryError in production before you need it
• ✓ Loading a whole file/result set? Stream it instead (Fix 3)
• ✓ In a container? Use -XX:MaxRAMPercentage=75, never -Xmx == container limit
• ✓ Process vanished with no Java error? That's exit 137, not this error

References

• OutOfMemoryError (Java SE API)
• HotSpot Virtual Machine Garbage Collection Tuning Guide (Oracle)