Heap Dump Analysis: From OutOfMemoryError to Root Cause

A heap dump is a snapshot of every object in the JVM's heap at a moment in time. When memory grows or the process dies with OutOfMemoryError, the dump is the definitive evidence: which objects exist, how big they are, and what keeps them alive.

This guide walks the full path — enabling automatic dumps, capturing manually, opening in Eclipse MAT, and turning a 'could be a leak' into a named class, an allocation site, and a fix.

Enable automatic dump on OOM

Best insurance: tell the JVM to dump the heap the moment it dies from OOM, so you always have a forensic artifact.

java -Xmx2g \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=/var/log/app.hprof \
  -jar app.jar

Capture manually with jmap/jcmd

Useful for investigating high heap before it OOMs. Find the PID, then dump live (reachable) objects.

jps -l
jcmd <pid> GC.heap_dump /tmp/heap.live.hprof
# or
jmap -dump:live,file=/tmp/heap.live.hprof <pid>

Open and read with Eclipse MAT

Launch MAT and File > Open Heap Dump. Start with the Overview > Leak Suspects, then drill into the Dominator Tree and Path to GC Roots.

# Launch MAT
MemoryAnalyzer /tmp/heap.live.hprof

Find the leak with a 2-dump diff

The classic trick: dump at T1 and T2 over a growing window. If a class's retained size roughly doubles with your growth rate, you've located the accumulation.

jcmd <pid> GC.heap_dump /tmp/h1.hprof
# ... run the workload ...
jcmd <pid> GC.heap_dump /tmp/h2.hprof
# In MAT: compare the Histograms or use the 'Compare' delta tool

Write an OQL query

OQL filters instances when the reports are too broad — e.g., list all your cache entries over a size threshold.

SELECT * FROM com.example.CacheEntry o WHERE o.@retainedHeapSize > 1048576