Java: java.lang.OutOfMemoryError: Java heap space
The heap could not satisfy an allocation after a full collection. Raising -Xmx only helps when the working set genuinely grew; if the cause is a leak, a bigger heap moves the crash later and makes the pauses worse. A heap dump taken at the moment of failure tells the two apart.
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.
# Always capture the evidence, in production too: the dump is written once
java -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/app.hprof -jar app.jar
# What the JVM decided it could use (containers: it reads the cgroup limit)
java -XX:+PrintFlagsFinal -version | grep -Ei 'MaxHeapSize|MaxRAMPercentage'
# In a container, set a share of the limit rather than a fixed number
java -XX:MaxRAMPercentage=75 -jar app.jar
# Watch live before reaching for a profiler
jcmd <pid> GC.heap_info
jcmd <pid> GC.class_histogram | head -25
# Then open the dump and look at the dominator tree
# Eclipse MAT, or: jhat / VisualVM
# Classic causes: an unbounded cache, a growing static Map,
# a result set read fully into memory, or too large a thread poolHow 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: MetaspaceMetaspace holds class metadata rather than objects, so raising the heap changes nothing. It…
- 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.