JVM Option: -XX:+HeapDumpOnOutOfMemoryError

-XX:+HeapDumpOnOutOfMemoryError is a JVM option that instructs the JVM to automatically generate a heap dump file when the application throws an OutOfMemoryError.

This option is critical for production-grade backend systems because it allows proper memory failure analysis instead of guessing the root cause.

When Was It Introduced?

This option was introduced in Java 6 and has been available in all later versions:

  • Java 6
  • Java 8
  • Java 11 (LTS)
  • Java 17 (LTS)
  • All modern JVM versions

What Problem Does It Solve?

Without this option:

When the application crashes with:

java.lang.OutOfMemoryError: Java heap space

You only know that memory was exhausted — but you do not know why.

With this option enabled:

The JVM automatically generates a heap dump file (.hprof) at the time of failure, allowing detailed memory analysis.

How to Enable It

Basic configuration:

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/opt/app/dumps/

If no path is specified, the dump file is generated in the current working directory.

What Is a Heap Dump?

A heap dump is a snapshot of the JVM heap memory at the moment of failure.

It contains:

  • All live objects
  • Object references
  • Class metadata
  • Retained heap sizes
  • GC roots

File format: .hprof

Heap dump size is usually close to the configured heap size.

Example: If -Xmx4g → dump file may be ~3–4 GB.

Why It Is Important in Backend Systems

Memory Leak Detection

Common backend memory issues:

  • Static collections growing indefinitely
  • Cache not evicting entries
  • Large in-memory buffers
  • Hibernate session leaks
  • Loading entire DB tables into memory

Heap dump helps identify:

  • Which class consumes the most memory
  • Which object retains references
  • The dominator tree (memory ownership hierarchy)

Production Debugging

In Kubernetes or Docker:

If the application crashes due to OOM:

  • Without heap dump → No clear root cause
  • With heap dump → Complete memory snapshot available

You can analyze using:

  • Eclipse MAT
  • VisualVM
  • JProfiler
  • YourKit

This drastically reduces Root Cause Analysis (RCA) time.

Important Considerations

Disk Space

Heap dumps can be very large. Ensure:

  • Sufficient disk space
  • Writable directory
  • Monitoring to avoid disk exhaustion

Containers (Docker / Kubernetes)

In container environments:

  • Ensure dump path is writable
  • Use a mounted volume for persistence
  • Otherwise dump may be lost when container restarts

Performance Impact

  • No runtime overhead during normal execution
  • Only triggered when OutOfMemoryError occurs
  • Safe to enable in production
  • This option does not prevent memory issues.
  • It ensures you have the evidence required to diagnose them properly.
This site uses Just the Docs, a documentation theme for Jekyll.