Java "OutOfMemoryError: Metaspace" During Build - Fix in CI

By Kaveh Alemi·Latchkey

The build JVM exhausted Metaspace, the region holding loaded class metadata. Many plugins, annotation processors, and class loading across a reused daemon fill Metaspace independently of the heap.

What this error means

The build fails with java.lang.OutOfMemoryError: Metaspace, often deep in a multi-module build or on a long-lived daemon that has accumulated class metadata. Heap may be fine; Metaspace is exhausted.

java runtime

FAILURE: Build failed with an exception.
* What went wrong:
java.lang.OutOfMemoryError: Metaspace
  at java.base/java.lang.ClassLoader.defineClass1(Native Method)

Common causes

Metaspace ceiling too low

A capped -XX:MaxMetaspaceSize (or a constrained container default) cannot hold the metadata for all the classes the build loads.

Class metadata accumulates on a reused daemon

A persistent Gradle daemon (or long Maven JVM) loads classes across builds without unloading, so Metaspace creeps up until it overflows.

How to fix it

Raise Metaspace and dump on OOM

Increase the Metaspace ceiling for the build JVM.

gradle.properties

# Gradle: gradle.properties
org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=1g -XX:+HeapDumpOnOutOfMemoryError
# Maven: export MAVEN_OPTS="-XX:MaxMetaspaceSize=1g"

Avoid daemon Metaspace creep in CI

Run without a reused daemon so class metadata does not accumulate across builds.

Terminal

./gradlew --no-daemon build

How to prevent it

Set -XX:MaxMetaspaceSize relative to the runner, prefer --no-daemon in ephemeral CI, and reduce class-heavy plugin churn.

Frequently asked questions

What causes "Build "OutOfMemoryError: Metaspace""?

A capped -XX:MaxMetaspaceSize (or a constrained container default) cannot hold the metadata for all the classes the build loads.

How do I fix Build "OutOfMemoryError: Metaspace"?