DEV Community: KiokuGraph

OutOfMemoryError - every variant, and what each one means

KiokuGraph — Wed, 19 Aug 2026 13:10:32 +0000

If you are here from a search at an awkward hour, the answer is below the fold and the commands are copy-pasteable.

The problem

Restarting makes it go away, which is exactly why it comes back on a schedule nobody has written down.

What actually finds it

Point KiokuGraph at the dump from the crash and it returns the dominator tree, the objects ranked by what they actually retain, and the line of your code responsible.

Read the full article

Details and the runbook: https://kiokugraph.io/blog/outofmemoryerror-complete-guide/

Anyone else been bitten by this in production?

Dominator trees explained, without the graph theory

KiokuGraph — Sat, 08 Aug 2026 01:49:20 +0000

Open any heap analyser and you meet the word "dominator" in the first thirty seconds, usually with
no explanation. It sounds like theory. It is the single most practical idea in memory analysis, and
it takes about three minutes to understand properly.

The problem it solves

A heap is a graph: objects pointing at objects, with cycles, shared references and no tidy hierarchy.

You want to answer one question: if I fix this, how much memory do I get back?

That question is hard to answer from the graph directly. An object can be referenced from five
places. Dropping one reference frees nothing, because the other four still hold it. Counting the
bytes "under" an object by walking its references double-counts everything shared, and in a real
heap almost everything is shared.

So a naive answer overstates wildly. You need to know what an object holds exclusively.

The definition, in one sentence

X dominates Y if every path from the GC roots to Y passes through X.

That is it. "Every path" is the load-bearing part.

GC roots are where reachability begins - stack locals of live threads, static fields, JNI
references. An object survives collection because some path leads to it from a root. If every
such path goes through X, then removing X removes the last way to reach Y, and Y becomes garbage.

So dominance means: X is single-handedly keeping Y alive.

A worked example

        [GC root]
            |
            v
          Cache
         /     \
        v       v
    Session   Session
        \      /
         v    v
        UserRecord

Cache dominates both Session objects. Every path from the root reaches them through Cache.
Cache also dominates UserRecord. There are two paths to it, but both pass through Cache, so it still qualifies.
Neither Session dominates UserRecord. Remove the left one and the right still reaches it.

The consequence is the useful bit. Drop Cache and all four objects below become collectable. Drop
one Session and nothing is freed - UserRecord survives via the other, and the Session
itself is only reclaimed if nothing else points at it.

This is why "which object has the most references?" is the wrong question and "which object
dominates the most bytes?" is the right one.

Retained size

The retained size of X is the total bytes of X plus everything X dominates. Equivalently: the
memory that becomes free if X becomes unreachable.

Contrast with shallow size, the bytes of the object itself - for a HashMap, about 48 bytes,
regardless of whether it holds three entries or three million.

That gap is what makes leaks findable:

Object	Shallow	Retained
`HashMap`	48 B	4.7 GB
`byte[]` (one of 27,000)	8 KB	8 KB
`String` (one of 1.2 M)	40 B	40 B

A histogram sorted by instance count puts String at the top and tells you nothing - a million
strings is what a healthy application looks like. Sorted by retained size, that 48-byte HashMap
appears first, and it is the outage.

The tree

Compute the dominator relationship for every object and you get a tree, because dominance has a
convenient property: each object has exactly one immediate dominator, the closest object that
dominates it. Link each to its immediate dominator and the messy graph becomes a tree.

The tree has two properties that make it worth the computation:

No double-counting. Every object appears exactly once. Retained sizes down the tree sum correctly, so the numbers can be trusted and compared.
Sorting by retained size ranks your problems. The top of the tree is, in order, the things whose removal frees the most memory. That is a work queue.

Note what the tree is not: it is not the reference graph. A dominator tree edge does not mean "X
has a field pointing at Y". It means "X is the last thing standing between Y and the collector".

How to read it during an incident

Sort by retained size, descending. Look at the top ten and no further at first.
Ignore the framework. The first entries are often a classloader, a thread pool or a connection pool. Those legitimately dominate a lot. You are looking for something yours.
Look for a small object with an enormous retained size. A static field, a cache, a listener list. That asymmetry is the signature of a leak.
Expand one level, not ten. The children tell you what is being retained - sessions? byte arrays? - which usually names the bug immediately.
Then ask why it is still reachable. The path from the GC root to that object is the code path that has to change.

Steps 1-4 usually take a couple of minutes. Step 5 is the actual debugging.

Why it is computed, not estimated

Dominance is a defined relation over a directed graph, not a heuristic. Two analysers over the same
dump produce the same dominator tree, or one of them is wrong. There is no tuning parameter and
nothing to interpret.

That matters when you are about to tell a room that the leak is in the session cache. "The analyser
thinks it might be here" invites argument. "Removing this frees 4.7 GB, and here is the reference
chain keeping it alive" ends the discussion.

The short version

Dominates = every path from a GC root passes through it = it is single-handedly keeping the object alive.
Retained size = what you get back if it goes away. Shallow size = the object alone.
Sort by retained size. Instance counts find noise; retained size finds leaks.
A small object with a huge retained size is the classic leak signature.
It is mathematics, not inference - which is why the number is arguable only if it is wrong.

KiokuGraph computes the dominator tree for JVM and .NET heaps and opens on
it sorted by retained size, so steps 1-4 above are the first screen. Free for a single dump.

KiokuGraph - Heap Dump Analyzer for JVM, .NET, Android and Kotlin

KiokuGraph — Sat, 08 Aug 2026 01:37:35 +0000

Reading an OutOfMemoryError: what the stack trace does and does not tell you

At 02:14 your service stops serving and the log says this:

java.lang.OutOfMemoryError: Java heap space
    at java.base/java.util.Arrays.copyOf(Arrays.java:3512)
    at java.base/java.lang.StringBuilder.append(StringBuilder.java:173)
    at com.acme.report.CsvWriter.writeRow(CsvWriter.java:88)
    at com.acme.report.ReportJob.run(ReportJob.java:141)

The instinct is to open CsvWriter.java:88 and start optimising the string handling.

That is almost always the wrong file.

What the stack trace actually says

The trace shows which allocation failed, not which code caused the heap to be full. Those are
different questions with usually different answers.

Think of it as a room filling with water. The stack trace names the last drop that made it overflow.
It says nothing about the tap that has been running for six hours.

CsvWriter asked for a slightly larger char[]. There was no room. CsvWriter is the victim - it
is simply the code unlucky enough to allocate at the moment the heap ran out. The real cause is
whatever is holding memory it should have released.

This is why the trace is often boringly generic. Arrays.copyOf, HashMap.resize,
ArrayList.grow - these appear constantly in OOM traces not because collections are the problem,
but because collections allocate frequently, so they are statistically likely to be holding the
glass when it overflows.

The useful signal in the trace is small: it tells you which thread died, which sometimes tells
you what the application was doing. Nothing more.

Read the message, not the trace

The first line is more informative than everything under it, because the JVM uses distinct messages
for genuinely distinct failures:

Message	What it means	Where to look
`Java heap space`	The heap is full and GC cannot reclaim enough.	A leak, or a heap too small for the workload. This is the common one.
`GC overhead limit exceeded`	Over 98% of time in GC, recovering under 2%.	Same causes as above, caught earlier. The JVM is thrashing.
`Metaspace`	Class metadata space exhausted.	Classloader leak. Look at redeploys, dynamic proxies, scripting engines - not your data.
`Requested array size exceeds VM limit`	A single array over ~2^31 elements.	A bug: an unbounded read, a corrupt length field. Not a leak.
`unable to create native thread`	The OS refused a thread.	Thread leak or an OS limit. The heap may be fine.
`Direct buffer memory`	Off-heap `ByteBuffer` exhausted.	NIO or Netty buffers not being released. A bigger heap will not help.

Two of these - Metaspace and Direct buffer memory - are frequently "fixed" by raising -Xmx,
which cannot possibly help because neither lives in the heap. If you take one thing from this
article, take that.

Leak or undersized?

Both produce Java heap space. They need opposite fixes, and you cannot tell them apart from the
trace. You need the shape of memory over time.

Enable GC logging - it is cheap enough for production:

-Xlog:gc*:file=/var/log/app/gc.log:time,uptime:filecount=5,filesize=20M

Then look at heap used after each full GC, not peak usage. Peak is noise; the post-collection
floor is the truth.

Sawtooth that returns to the same floor → not a leak. The workload needs more room than it has, or allocation is too aggressive.
Floor climbing steadily over hours or days → a leak. Something retains objects across collections, and no heap size will save you. It buys time proportional to the size increase, and then fails again.

A leak that takes a week to kill a 4 GB heap will take two weeks to kill an 8 GB one. Doubling
-Xmx is a scheduling decision, not a fix.

Get the dump

The trace cannot tell you what is retained. Only the heap can, so capture it:

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/dumps

This writes an .hprof at the moment of failure, costs nothing until it triggers, and should be on
in every production JVM. Without it, an OOM at 02:14 leaves you with a stack trace naming an
innocent bystander.

To capture from a running JVM before it dies:

jcmd <pid> GC.heap_dump /var/dumps/app.hprof

Two warnings. It pauses the JVM for roughly a second per gigabyte - do it on one instance out of the
pool. And the file is the size of your live set, so check disk first; a dump that fills the volume
turns one incident into two.

Then ask the only question that matters

With a dump open, ignore what is numerous and find what is retained.

Those differ, and the distinction is the whole game:

Shallow size - the bytes of one object alone.
Retained size - the bytes that would be freed if it were collected: itself plus everything only reachable through it.

A million String objects sounds alarming and usually is not - they are shared, referenced from
everywhere, and collecting any one frees 40 bytes. One HashMap with a shallow size of 48 bytes and
a retained size of 4.7 GB is your outage. It is the only thing holding those million strings,
and dropping it frees all of them.

Sort by retained size, look at the top ten, and the leak is almost always visibly there. In practice
it is one of five things:

A static collection that is only ever added to
Listeners or callbacks registered and never removed
ThreadLocal values on a pooled thread that outlives the request
A cache with no eviction policy
A classloader retained by a stray reference, keeping an entire old deployment alive

The short version

The stack trace names the failed allocation, not the cause. Do not start there.
Read the message. Metaspace and Direct buffer memory are not heap problems and ignore -Xmx.
Use GC logs to tell a leak from an undersized heap: watch the floor after full GC, not the peak.
Turn on -XX:+HeapDumpOnOutOfMemoryError now, before you need it.
In the dump, sort by retained size. The answer is nearly always in the top ten.

KiokuGraph computes dominator trees and retained sizes for JVM and .NET
dumps, so the ranking above is the first screen rather than something you assemble by hand. Free for
a single dump - no signup needed to try it.