Scala sbt "OutOfMemoryError: Metaspace" in CI

The sbt JVM ran out of Metaspace, the region that holds class metadata. The Scala compiler and a large dependency tree load many classes, and a low Metaspace cap fills before the build finishes.

What this error means

sbt aborts mid-build with "java.lang.OutOfMemoryError: Metaspace", sometimes after "Compiling N Scala sources". The same project may build on a developer machine with more memory.

sbt

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

Common causes

Metaspace cap too low for the compiler and deps

A constrained -XX:MaxMetaspaceSize cannot hold the metadata for the Scala compiler plus a wide dependency graph.

Class metadata accumulates across reloads

Repeated project reloads or many subprojects load class metadata that is not reclaimed before the cap is reached.

How to fix it

Raise the sbt JVM Metaspace limit

Give the launcher more Metaspace through JAVA_OPTS or .jvmopts so class metadata fits.

Terminal

export JAVA_OPTS="-Xmx2g -XX:MaxMetaspaceSize=1g"
sbt compile

Set memory in .jvmopts so CI inherits it

Commit a .jvmopts file so every sbt invocation, local and CI, starts with the same limits.

.jvmopts

-Xmx2g
-XX:MaxMetaspaceSize=1g

How to prevent it

Commit .jvmopts so memory settings are consistent in CI.
Size Metaspace to the compiler and dependency footprint, not the default.
Avoid unnecessary reload cycles inside a single CI job.