sbt "java.lang.OutOfMemoryError: Metaspace" in CI

By Daniel Zoghalchali·Latchkey

The JVM hosting sbt ran out of Metaspace, the region that holds class metadata. Scala compilation loads many classes, and a capped MaxMetaspaceSize or an accumulating sbt session overflows it. Raising the limit through SBT_OPTS fixes it.

What this error means

sbt fails mid-compile with "java.lang.OutOfMemoryError: Metaspace" and the build may abort or the sbt process die.

[error] java.lang.OutOfMemoryError: Metaspace
[error] Use 'last' for the full log.
[error] (Compile / compileIncremental) java.lang.OutOfMemoryError: Metaspace

Common causes

MaxMetaspaceSize capped too low

An explicit -XX:MaxMetaspaceSize in SBT_OPTS or the launcher is smaller than a large multi-module Scala compile needs.

Long-lived sbt session accumulating classes

A persistent sbt session that reloads and compiles many times keeps loading classes until Metaspace fills.

How to fix it

Raise Metaspace via SBT_OPTS

1. Set a larger -XX:MaxMetaspaceSize in SBT_OPTS for the CI step.
2. Run sbt so the launcher picks up the bigger limit.
3. Confirm the compile completes without the OOM.

env:
  SBT_OPTS: "-Xmx2g -XX:MaxMetaspaceSize=1g"

Run sbt in batch mode so the JVM exits

Batch each job so the sbt JVM starts fresh and releases Metaspace instead of accumulating across many interactive commands.

sbt --batch clean compile test

How to prevent it

• Set an adequate -XX:MaxMetaspaceSize in SBT_OPTS for large builds.
• Run one batched sbt invocation per job so the JVM does not accumulate classes.
• Provision runners with enough memory for the compile.

Frequently asked questions

Related guides

References

• Apache Maven guides
• Gradle user manual
• GitHub Actions documentation