Gatling "java.lang.OutOfMemoryError: Java heap space" in CI

Gatling runs on the JVM, and injecting many concurrent users or buffering large response bodies can exhaust the heap. When it does, the JVM throws OutOfMemoryError and the simulation dies mid-run.

What this error means

The run aborts with "java.lang.OutOfMemoryError: Java heap space" and an incomplete report, typically only at higher injection profiles on a small runner.

Gatling

Exception in thread "gatling-http-1" java.lang.OutOfMemoryError: Java heap space
	at io.netty.buffer.PoolArena.allocate(PoolArena.java:...)

Common causes

Heap too small for the injection profile

The default JVM heap cannot hold the state for thousands of concurrent users plus their in-flight responses.

Large response bodies buffered in memory

Saving or checking big response bodies for every request accumulates buffers that fill the heap.

How to fix it

Raise the JVM heap for the load generator

Give the Gatling JVM more heap via MAVEN_OPTS or JAVA_OPTS before the run.

Terminal

export MAVEN_OPTS="-Xms1g -Xmx4g"
./mvnw gatling:test

Stop buffering large bodies and scale out

Avoid saving or asserting on large response bodies you do not need.
Reduce concurrent users per generator, or split across distributed generators.
Use a larger runner when a single generator must hold the whole profile.

LoadSimulation.scala

.check(status.is(200)) // avoid bodyString checks on large payloads

How to prevent it

Size -Xmx to the injection profile before running.
Do not buffer or assert on large response bodies you do not need.
Split heavy load across distributed generators rather than one JVM.