Java: java.lang.OutOfMemoryError: Metaspace
Metaspace holds class metadata rather than objects, so raising the heap changes nothing. It fills when an application keeps loading classes: repeated hot redeploys inside one JVM, a proxy or scripting library generating a class per request, or a classloader kept alive by a single stray reference.
Quick fix
Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.
# Watch the class count, not the heap
jcmd <pid> VM.native_memory summary | grep -A3 Class
jstat -gcmetacapacity <pid> 1000 5
# Which loaders are still alive, and what is holding them
jmap -clstats <pid>
jcmd <pid> GC.class_stats # needs -XX:+UnlockDiagnosticVMOptions
# A ceiling turns a slow leak into a clear, early failure
java -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError \
-XX:HeapDumpPath=/var/log/app -jar app.jar
# Hot redeploys leak loaders by design: restart the JVM per deploy
# and look for ThreadLocals and JDBC drivers pinning the old loaderHow to diagnose Java errors
Java errors concentrate at the class loading boundary (ClassNotFoundException, NoClassDefFoundError, UnsupportedClassVersionError) and around resource pools under load. Class loading errors are almost always classpath or version problems rather than missing code. UnsupportedClassVersionError in particular is a pure bytecode-version mismatch and tells you exactly which JDK compiled the class.
If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.
- Print the actual runtime version with
java -versionand compare it against your build target. Major bytecode version 65 is Java 21, 61 is Java 17, 52 is Java 8. - Inspect the resolved dependency tree (
mvn dependency:tree,gradle dependencies) to find duplicate or conflicting versions of the same library. - For pool exhaustion, log pool metrics (HikariCP exposes active, idle and pending counts). Exhaustion means connections are not being returned, which is a try-with-resources problem.
- Enable
-verbose:classtemporarily to see which jar a class is loaded from when two versions are on the classpath. - Capture a heap dump on OOM with
-XX:+HeapDumpOnOutOfMemoryErrorand analyse it rather than raising-Xmxblindly.
Tools worth reaching for
mvn dependency:treejcmd / jstack / jmap-verbose:classEclipse MATJFR (Java Flight Recorder)
Authoritative references
Primary documentation for this error, worth reading before applying any fix in production.
Related Java errors
- Cannot get a connection, pool errorThe database connection pool (HikariCP, DBCP, etc.) has no available connections. All…
- ClassCastExceptionAn object was cast to a type it is not an instance of. Common when using raw types or…
- ConcurrentModificationExceptionA collection was modified while being iterated over. This can happen in single-threaded code…
- Could not resolve dependenciesMaven or Gradle cannot download or resolve project dependencies. May be caused by missing…
- Java: Cannot invoke "String.length()" because "s" is nullThis is a helpful NullPointerException message, on by default since Java 15, and it names the…
- Java: error: invalid target release: 21The build asked javac for a release the JDK on PATH cannot produce, which means the compiler…
- Java: java.lang.OutOfMemoryError: Java heap spaceThe heap could not satisfy an allocation after a full collection. Raising -Xmx only helps…
- Java: NoClassDefFoundError: Could not initialize class XThis is not a missing class. The class was found, its static initialiser ran and threw, and…
Browse other categories
- HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
- JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
- Database 41Connections, deadlocks, constraints, replication and memory limits.
- AI 35Rate limits, context windows, GPU memory and model-serving failures.
- Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
- Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
- Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
- Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
- System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
- Cloud 25IAM permissions, quotas, service limits and credential failures.
- Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
- TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.
Something missing or wrong?
This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.