Understanding java.lang.OutOfMemoryError: Metaspace and How to Resolve It

Java defines several java.lang.OutOfMemoryError subclasses, each representing a distinct memory problem; among them java.lang.OutOfMemoryError: Metaspace is particularly tricky.

When the class and method definitions stored in Metaspace exceed the memory limit set by the JVM option -XX:MaxMetaspaceSize , the JVM throws java.lang.OutOfMemoryError: Metaspace .

Metaspace is the JVM area that holds class metadata such as class names, methods, and fields. It resides in native memory, separate from the Java heap.

Insufficient Metaspace can affect the entire JVM, leading to crashes or performance degradation, especially under high‑load production conditions.

What Causes java.lang.OutOfMemoryError: Metaspace?

Common reasons include:

Dynamic creation of many classes : using scripting languages (e.g., Groovy), Java reflection, dynamic proxies, or bytecode enhancement tools like CGLIB or ASM generates new classes at runtime, continuously loading metadata into Metaspace.

Loading a large number of classes : the application itself or third‑party libraries/frameworks contain many classes.

Loading many class loaders : frequent creation or loading of class loaders.

Class loader leaks : class loaders are not properly reclaimed, preventing metadata from being released.

Solutions

Increase Metaspace size : adjust JVM parameters, e.g., -XX:MetaspaceSize and -XX:MaxMetaspaceSize , to enlarge the Metaspace region. This usually resolves most issues because Metaspace rarely leaks.

Fix memory leaks : analyze the application for memory‑leak problems and ensure that unused class definitions can be garbage‑collected.

Optimize class loading : reduce unnecessary dynamic class loading and avoid class‑loader leaks.

How to Diagnose OutOfMemoryError: Metaspace

Two common methods are:

1. Use -verbose:class (Java 8 and earlier)

Start the application with the -verbose:class flag; the JVM prints loaded class information to the console. Example:

java {app_name} -verbose:class

Frequent class names provide important clues for troubleshooting.

2. Use -Xlog:class+load (Java 9 and later)

Start the application with -Xlog:class+load ; the JVM logs class‑loading details to a specified file. Example:

java {app_name} -Xlog:class+load=info:/opt/log/loadedClasses.txt

If class names still do not pinpoint the issue, further analysis of a heap dump may be required.