How to Troubleshoot 'java.lang.OutOfMemoryError Metaspace' Errors

Applies To

Java SE JDK and JRE - Version 8 and later
Any platform

## Introduction

This document provides a background and some suggestions for troubleshooting Java memory issues indicated by java.lang.OutOfMemoryError: Metaspace errors.

In Java SE 8, there is no Permanent Generation space involved. The class metadata is now stored in the Metaspace, which is allocated out of native memory. This means that it is limited by the amount of native memory available on the machine. However, Metaspace size can also be limited by using the MetaspaceSize and MaxMetaspaceSize options.

You can learn more about Class Metadata from Java SE 8 GC Tuning Guide - Class Metadata.

Troubleshooting Steps

The primary cause for the java.lang.OutOfMemoryError: Metaspace message is either too many classes, or classes that are too big, being loaded to the Metaspace.

If you have not set the MaxMetaspaceSize option, your application will only be limited by the memory resources on the system. If you are seeing the OutOfMemoryError: Metaspace message, here are some suggestions:

1. As a start, you will want to enable diagnostic Garbage Collection information to help to understand what is the baseline use of the application. Enable Garbage Collection logging by adding the following Java options and monitor the Metaspace size at each Full GC.

   -XX:+PrintGCDetails -XX:+PrintGCTimeStamps -Xloggc:<GC LOG FILENAME>

   Look for the “Metaspace” output from the log at a Full GC collection to see if the space is being collected or continues to be filled up. For example:

   xxx: [Full GC (Ergonomics) [PSYoungGen: 479734K->299200K(1846272K)] [ParOldGen: 5564656K->5592539K(5592576K)] 6044390K->5891740K(7438848K), [Metaspace: 526174K->525063K(1525760K)], 35.8870665 secs] ...

2. A. If you are using the ConcurrentMarkSweep Garbage Collector, and the Metaspace keeps increasing after each Full GC, you may want to add the following option to ensure that classes are unloaded with the CMS collection cycle:

   -XX:+CMSClassUnloadingEnabled

   B. If you are using the G1, and the Metaspace keeps increasing after each Full GC, you may want to add the following option to ensure that classes are unloaded with the CMS collection cycle:

   -XX:+ClassUnloadingWithConcurrentMark

3. The cause could also be due to ClassLoader leaks. To narrow this down further, add the following options and study the output to find out which classes were loaded and which ones were not unloaded:

   -XX:+TraceClassLoading -XX:+TraceClassUnloading

   Or use jmap which prints out similar information about the classloaders and their liveness, including the number and sizes in the Metaspace.

   jmap -clstats <pid>

   You can also use Native Memory Tracking (NMT) to track the number of loaded classes and the memory used since Metaspace comes from native memory.

   As an example on how to start the Java process with NMT enabled, first choose the level of output details by adding one of these options to the Java application’s startup options:

   -XX:NativeMemoryTracking=summary

   or

   -XX:NativeMemoryTracking=detail

   After the application has started, and at selected intervals based on your understanding of the growth of the Metaspace memory, execute the following command to obtain the JVM’s native memory usage:

   jcmd <pid> VM.native_memory

   More details can be obtained in Java SE 8 Native Memory Tracking Troubleshooting.

4. Make sure -Xnoclassgc is not being used unless there is a need for it. This will turn off class unloading.

5. If you have set the MaxMetaspaceSize option and still run out of Metaspace, increase the MaxMetaspaceSize to see if the issue can be resolved:

   -XX:MetaspaceSize=<NNN> -XX:MaxMetaspaceSize=<NNN>

   where NNN is number that can include ‘m’ or ‘M’ for megabytes, ‘k’ or ‘K’ for kilobytes, and ‘g’ or ‘G’ for gigabytes.

If increasing the MetaspaceSize or MaxMetaspaceSize does not help, use steps 1 through 4 to further troubleshoot the issue.

Last reviewed on Sat Feb 01 2025 00:00:00 GMT+0000 (Coordinated Universal Time)