java.lang.OutOfMemoryError in CI

By Daniel Zoghalchali·Latchkey

The JVM threw OutOfMemoryError because it could not allocate within its heap (or the OS could not give it more). In CI this surfaces during builds, large test runs, or data processing.

What this error means

A Java step throws OutOfMemoryError: Java heap space or GC overhead limit exceeded. Raising -Xmx or using a larger runner usually fixes a one-off spike; a steadily growing footprint points to a leak.

shell

Exception in thread "main" java.lang.OutOfMemoryError: Java heap space
	at com.example.Build.run(Build.java:42)

Common causes

Heap limit (-Xmx) too low for the workload

A large compile, test, or batch job needs more heap than configured and the JVM aborts.

A memory leak in the application or test

A genuine leak grows usage until any heap is exhausted; raising -Xmx only delays it.

How to fix it

Tune the JVM heap below the runner RAM

Set -Xmx with headroom under the runner ceiling.

shell

export JAVA_TOOL_OPTIONS="-Xmx3g -XX:MaxMetaspaceSize=512m"
./gradlew build

Distinguish a spike from a leak

If usage is steady and just above the limit, raise -Xmx or use a larger runner.
If usage climbs continuously, capture a heap dump (-XX:+HeapDumpOnOutOfMemoryError) and fix the leak in your code.
Lower test parallelism to reduce concurrent heap pressure.

How to prevent it

Size -Xmx to the runner, not the laptop.
Add heap-dump-on-OOM in CI to diagnose leaks.
Right-size memory for JVM-heavy builds.

Frequently asked questions

What causes "java OutOfMemoryError"?

A large compile, test, or batch job needs more heap than configured and the JVM aborts.

How do I fix java OutOfMemoryError?

Set -Xmx with headroom under the runner ceiling.

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.

References

GitHub Actions documentation