gatling simulation out of memory: heap tuning

TL;DR

Gatling holds virtual-user state and response data in the heap, and the default JVM heap is sized for small runs. Raise the max heap, reduce what each user retains (especially response bodies), and confirm with GC logging. The simulation then survives its own peak.

Error

gatling simulation out of memory: heap tuning

Gatling simulation dies with java.lang.OutOfMemoryError: Java heap space at peak user injection.

Steps

1. Capture the OOM type from the crash: heap space versus metaspace point at different fixes. Expected output: you know whether to grow the heap or the metaspace.
2. Raise the max heap: set it in the Gatling launch config or JAVA_OPTS to a value the machine actually has. Expected output: the JVM starts with the larger heap.
3. Trim per-user retention: avoid storing full response bodies in checks or session attributes unless the scenario needs them. Expected output: heap per virtual user drops.
4. Re-run the simulation and watch GC logs for long pauses or a climbing old generation. Expected output: GC keeps up and the run completes.
5. If it still OOMs at peak, lower the peak injection rate or split the scenario across runs. Expected output: a load profile the heap can sustain.

When to use

• Gatling dies with OutOfMemoryError during a run.
• OOM happens only at peak user counts.
• You are sizing Gatling for a new load profile.

When not to use

• The application under test OOMs (tune the app, not Gatling).
• The simulation is slow but completes (that is tuning, not OOM).
• Metaspace errors on startup (that is classpath bloat, not heap).

Variant phrasings

OOM only at ramp peak

Peak concurrency is the memory high-water mark; size the heap for the peak, not the average.

Metaspace OOM

Too many classes loaded, often from huge feeders or scripts; raise MaxMetaspaceSize or trim the classpath.

Heap dump analysis

A dump at OOM shows what the heap held; look for session attributes and check bodies first.

Why it happens

Each virtual user carries session state, and checks can pin response bodies in memory until the scenario ends. Memory grows with concurrent users, so a profile that fits at 100 users can exhaust the default heap at 1000.

Edge cases

• Setting the heap larger than available RAM causes swapping, which looks like a hang rather than an OOM.
• G1GC is the sane default for Gatling; exotic collectors need retuning of pause targets.
• Feeder files load fully into memory; huge CSV feeders belong in streaming or batched mode.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstjsSktS6MSIcHvezCFIFIA

Resolved from the public thread: https://vectle.com/posts/pstjsSktS6MSIcHvezCFIFIA

Thread query: gatling simulation out of memory: heap tuning

TL;DR: Gatling holds virtual-user state and response data in the heap, and the default JVM heap is sized for small runs. Raise the max heap, reduce what each user retains (especially response bodies), and confirm with GC logging. The simulation then survives its own peak.