What Triggers OutOfMemoryError Variants?

The error message names the resource that ran out, and that is the fastest way to know which problem you have.

Java heap space means the heap is exhausted. Either the live data set genuinely exceeds the heap — in which case the answer is more memory or a smaller working set — or something is being retained that should not be, which is a leak. This is the variant you will meet most often.

Metaspace means the class metadata area is exhausted. It happens when the program loads classes continuously, usually because a class loader is being recreated and each one loads its own copies of the classes. It is a native memory problem, so it is not fixed by raising the heap size.

Unable to create new native thread means the process cannot get another thread from the operating system. The cause is usually the number of threads rather than their size — a thread-per-request design with no bound, or a platform limit on the number of threads per process.

Direct buffer memory means the direct byte buffers allocated outside the heap have exhausted the limit. It usually shows up just after a garbage collection, because the buffers are only reclaimed then.

GC overhead limit exceeded means the collector spent nearly all of its time collecting and reclaimed almost nothing — the classic sign of a heap that is too small for the live data set, so almost everything is live.

And Requested array size exceeds VM limit means you asked for an array bigger than the JVM will allow, usually because of an integer overflow in a size calculation — a multiplication that wrapped around and produced a negative number that became a huge unsigned value.

The message is the first diagnostic, and it is worth knowing that each variant points at a different place to look. The heap-space variant means you need a heap dump and a dominator analysis. The Metaspace variant means you need to look at class loading — usually a class loader that is never released. The thread variant means you need to count threads and look at the platform limits. The direct-buffer variant means you need to look at the code that allocates off-heap buffers.

public class Main {
    public static void main(String[] args) {
        java.lang.management.MemoryMXBean memory =
                java.lang.management.ManagementFactory.getMemoryMXBean();
        long max = memory.getHeapMemoryUsage().getMax();
        long used = memory.getHeapMemoryUsage().getUsed();

        System.out.println("heap max MB  : " + max / (1024 * 1024));
        System.out.println("heap used MB : " + used / (1024 * 1024));
        System.out.println("headroom MB  : " + (max - used) / (1024 * 1024));

        // The error message names the pool that ran out:
        //   java.lang.OutOfMemoryError: Java heap space
        //   java.lang.OutOfMemoryError: Metaspace
        //   java.lang.OutOfMemoryError: unable to create new native thread
        //   java.lang.OutOfMemoryError: direct buffer memory
        //   java.lang.OutOfMemoryError: GC overhead limit exceeded
        System.out.println("the message names the resource that ran out");

        // Thread count is the tell for the thread variant.
        java.lang.management.ThreadMXBean threads =
                java.lang.management.ManagementFactory.getThreadMXBean();
        System.out.println("live threads : " + threads.getThreadCount());
    }
}

The output shows the headroom you had left and the number of live threads. The headroom tells you whether you were close to the limit, and the thread count is the first thing to check when you suspect the thread variant.

Two things that catch people out. Because OutOfMemoryError extends Error rather than Exception, a catch block for Exception will not catch it — so if you want to handle it, you have to catch Throwable explicitly, which is usually the wrong thing to do. And catching it and carrying on is rarely a good idea: if the heap is exhausted, the next allocation fails too, and the application is in a corrupted state. Letting the process die and be restarted by a supervisor is usually the safer behaviour.

The one case where catching it is right is when you can release something significant and try again — closing a large buffer, clearing a cache, dropping a reference to a big data set — and then the operation can genuinely be retried.

They exhaust completely different resources, and the diagnosis follows from that. The heap space error means the region of memory that holds your objects is full. The Metaspace error means the region that holds class metadata is full — the runtime representation of your classes, their constant pools, their methods and their bytecode.

The symptoms differ in a useful way. A heap error usually appears as the application slowing down first, because the collector is working harder, and then failing when something tries to allocate an object. A Metaspace error tends to appear in a program that is loading classes continuously — a dynamic proxy created per request, a scripting engine compiling a script per call, or a framework that reloads configuration and builds new classes each time.

How to tell them apart in practice. The message names the resource. If the heap usage is comfortably below its limit at the moment of the failure, the problem is not the heap. And you can watch the two areas separately with the management API: the heap usage is on the heap side, the class metadata is on the non-heap side, and if the non-heap number is the one climbing, you are looking at class loading rather than at object retention.

The fixes are completely different as well. A heap error is fixed by reducing what you retain or by giving the process more heap. A Metaspace error is fixed by stopping the class loading — reusing the class loader, caching the proxy, or hoisting the compilation out of the request path — and only in extremis by raising the Metaspace limit, which merely postpones the problem.

Here is the same thing as runnable code:

public class Main {
    public static void main(String[] args) {
        java.lang.management.MemoryMXBean memory =
                java.lang.management.ManagementFactory.getMemoryMXBean();
        java.lang.management.MemoryUsage heap = memory.getHeapMemoryUsage();
        java.lang.management.MemoryUsage nonHeap = memory.getNonHeapMemoryUsage();

        System.out.println("heap used MB   : " + heap.getUsed() / (1024 * 1024));
        System.out.println("heap max MB    : " + heap.getMax() / (1024 * 1024));
        System.out.println("non-heap used MB: " + nonHeap.getUsed() / (1024 * 1024));
        System.out.println("non-heap max MB : " + nonHeap.getMax() / (1024 * 1024));

        // The non-heap figure is where class metadata lives.
        System.out.println("metaspace is outside the Java heap");
        System.out.println("a heap error is fixed by retaining less;"
                + " a metaspace error by loading fewer classes");
    }
}