sbt "GC overhead limit exceeded" in CI

By Kaveh Alemi·Latchkey

The JVM aborted because it was spending over 98% of its time in garbage collection while recovering less than 2% of the heap. For sbt this means the heap (-Xmx) is too small for the compile or test workload. Raise it via SBT_OPTS.

What this error means

sbt fails with "java.lang.OutOfMemoryError: GC overhead limit exceeded" during compilation or a memory-heavy test.

[error] java.lang.OutOfMemoryError: GC overhead limit exceeded
[error] (Compile / compileIncremental) java.lang.OutOfMemoryError:
GC overhead limit exceeded

Common causes

Heap too small for the build

A default or low -Xmx cannot hold the working set of a large Scala compile, so the collector thrashes without freeing enough memory.

A memory-heavy test or code generation step

A test or macro/codegen step allocates heavily and outgrows the configured heap.

How to fix it

Increase the heap through SBT_OPTS

1. Set a larger -Xmx in SBT_OPTS for the sbt step.
2. Run sbt so the launcher applies the new heap size.
3. Confirm the build completes without the GC error.

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

Reduce peak memory pressure

Lower forked-test parallelism or split heavy modules so the working set fits the available heap.

Test / parallelExecution := false

How to prevent it

• Set -Xmx in SBT_OPTS to match the build's real memory need.
• Provision runners with headroom above the JVM heap.
• Split very large modules to cap peak memory per compile.

Frequently asked questions

Related guides

References

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