sbt forked test OutOfMemoryError in CI

By Daniel Zoghalchali·Latchkey

Tests run in a forked JVM that does not inherit sbt own memory flags. That child process ran out of heap or Metaspace and crashed the test run.

What this error means

Tests fail with java.lang.OutOfMemoryError even though compilation succeeded. It can be intermittent under load: the forked JVM dies only when memory is tight.

sbt

[error] Uncaught exception when running tests: java.lang.OutOfMemoryError: Java heap space
[error] Test run finished. Forked JVM exited unexpectedly.

Common causes

Forked test JVM uses defaults

With fork := true, the test JVM starts fresh and ignores SBT_OPTS, so it gets the JVM default heap.

Tests load heavy fixtures

In-memory databases, large datasets, or leaked resources push the forked JVM past its small default heap.

How to fix it

Pass memory options to the forked JVM

Set javaOptions in the Test scope so the child JVM gets enough memory.

build.sbt

Test / fork := true
Test / javaOptions ++= Seq("-Xmx2g", "-XX:MaxMetaspaceSize=512m")

Reduce per-test memory pressure

Close resources in test teardown to avoid leaks.
Limit parallel test forks if each is memory heavy.
Stream large fixtures instead of loading them whole.

Use a larger runner

For genuinely heavy suites, move to a higher-RAM runner. Latchkey managed runners auto-retry transient OOM crashes and offer larger-RAM sizes for memory-intensive test runs.

How to prevent it

Set Test / javaOptions explicitly when forking.
Bound parallel forks to fit runner memory.
Profile memory-hungry test suites.

Frequently asked questions

What causes ""OutOfMemoryError" in forked tests"?

With fork := true, the test JVM starts fresh and ignores SBT_OPTS, so it gets the JVM default heap.

How do I fix "OutOfMemoryError" in forked tests?