sbt "java.lang.OutOfMemoryError" during compile in CI

By Daniel Zoghalchali·Latchkey

The sbt compiler JVM exhausted its heap while compiling. Large Scala codebases, macro expansion, and implicit derivation allocate aggressively during compile.

What this error means

The build dies with java.lang.OutOfMemoryError: Java heap space or GC overhead limit exceeded mid-compile. It can be intermittent on a tight runner: the same build passes with more memory.

sbt

[error] java.lang.OutOfMemoryError: Java heap space
[error]   at scala.tools.nsc.... (compiler)
[error] (Compile / compileIncremental) java.lang.OutOfMemoryError: Java heap space

Common causes

Default heap too small for the project

Without explicit limits the JVM heap is modest. Large module graphs and macro-heavy libraries push past it during a full compile.

Runner is memory-starved

A small runner has no headroom for the compiler heap plus the rest of the build, so allocation fails partway through.

How to fix it

Raise the sbt JVM heap

Give sbt more memory through .sbtopts or the environment.

.sbtopts

# .sbtopts
-J-Xmx4g
-J-XX:ReservedCodeCacheSize=256m

Set memory via SBT_OPTS in CI

Export the heap limit for the CI step without editing files.

CI step

export SBT_OPTS="-Xmx4g"

Use a larger runner

For genuinely heavy builds, move to a higher-RAM runner. Latchkey managed runners self-heal transient OOM kills by auto-retrying and offer larger-RAM sizes for memory-heavy Scala compiles.

How to prevent it

Set -Xmx explicitly for reproducible compiles.
Split monoliths into subprojects to cut per-JVM load.
Right-size the runner to the project.

Frequently asked questions

What causes ""OutOfMemoryError" during compile"?