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.

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