Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gatling/gatling.io-doc/llms.txt

Use this file to discover all available pages before exploring further.

Debugging a Gatling simulation is different from debugging a typical application because the engine drives thousands of virtual users concurrently through an async, non-blocking pipeline. Knowing the right tools — from simple session value printing to full HTTP trace logging and step-through IDE debuggers — saves significant time when tracking down a misbehaving check, an unexpected session value, or a request that refuses to return 200.

​
Printing Session Values

The quickest way to inspect what a virtual user holds in its session is a targeted exec block that logs a specific key to stdout. 
// Java
scenario("Debug Session")
  .exec(session -> {
    System.out.println("accessToken = " + session.getString("accessToken"));
    return session;
  })

// TypeScript
scenario("Debug Session")
  .exec((session) => {
    console.log("accessToken =", session.get("accessToken"));
    return session;
  })
Only use System.out.println / console.log during development with a single virtual user. Standard output is a blocking, synchronous operation. Under any meaningful load it will freeze Gatling’s async engine and corrupt your test results. Remove all print statements before running at scale.

​
Logback Configuration

Gatling ships with a logback.xml file inside the conf/ directory of your project. This is your primary lever for controlling HTTP request and response logging.

​
Enabling HTTP Logging

Open src/test/resources/logback.xml (or conf/logback.xml in the standalone bundle) and uncomment the appropriate logger: 
<!-- Log ALL HTTP requests and responses (every status) -->
<logger name="io.gatling.http.engine.response" level="TRACE" />

<!-- Log only FAILED HTTP requests and responses -->
<!-- <logger name="io.gatling.http.engine.response" level="DEBUG" /> -->
Logs every request and response regardless of outcome. Use this when you need to understand exactly what Gatling is sending and receiving — headers, bodies, redirects, and all.

​
Directing Logs to a File

By default, Logback prints to the console. When a scenario is large, it helps to capture logs in a file you can open in a browser or search with grep. 
<!-- logback.xml -->
<appender name="FILE" class="ch.qos.logback.core.FileAppender">
  <file>/tmp/gatling-debug.log</file>
  <append>true</append>
  <encoder>
    <pattern>%d{HH:mm:ss.SSS} [%-5level] %logger{15} - %msg%n%rEx</pattern>
  </encoder>
</appender>

<root level="WARN">
  <appender-ref ref="FILE" />
</root>
Run with atOnceUsers(1) and TRACE logging, then open the log file in your browser to read the raw HTML responses. This is extremely helpful for diagnosing check failures caused by dynamic tokens or CSRF fields.

​
Using the Java Debugger (Maven and Gradle)

For complex logic — custom feeders, session transformations, or conditional flow — a full step-through debugger is invaluable. Gatling 3.13.4+ supports attaching a JVM debugger when launched from Maven or Gradle.
Minimum versions required:
  • Gatling 3.13.4
  • gatling-maven-plugin 4.14.0
  • gatling-gradle-plugin 3.13.4

​
Maven with IntelliJ IDEA

1

Open Run/Debug Configurations

Click Add Configuration or Edit Configurations to the left of the Run/Debug buttons in the top toolbar.
2

Add a Maven configuration

Click the + sign and select Maven.
3

Set the command line

Enter gatling:test -Dgatling.sameProcess=true in the Command line field.
4

Add JVM options

Click Modify options → Add JVM options and enter:
--add-opens=java.base/java.lang=ALL-UNNAMED
5

Launch the debugger

Click the Debug button (not Run). IntelliJ will stop at any breakpoints you have set in your simulation code.

​
Gradle with IntelliJ IDEA

1

Open Run/Debug Configurations

Click Add Configuration or Edit Configurations in the top toolbar.
2

Add a Gradle configuration

Click + and select Gradle.
3

Set the task

Enter gatlingRun --same-process in the Task and arguments field.
4

Add VM options

Click Modify options → Add VM options and enter:
--add-opens=java.base/java.lang=ALL-UNNAMED
5

Launch the debugger

Click the Debug button. Breakpoints in your simulation will be hit as Gatling executes.

​
Common Errors and Solutions

Check failed: status 302 found when expecting 200

The server is redirecting but your protocol builder doesn’t follow redirects. Add .followRedirectsMax(5) to your HttpProtocolBuilder, or check whether you need to set the correct Accept or Content-Type header.

Session key missing / NullPointerException in EL expression

A .saveAs("key") check was not reached, or it failed silently. Enable DEBUG logging and trace the exact request to confirm the check ran and that the JSON path or regex returned a value.

Feeder exhausted

Your CSV or JSON feeder ran out of records before the simulation ended. Switch from the default .queue() strategy to .circular() to loop indefinitely, or generate a larger data file.

Open files limit exceeded

At high concurrency on Linux/macOS, the OS file-descriptor limit is hit. Run ulimit -n 65536 before starting Gatling, or configure it permanently in /etc/security/limits.conf.

​
Debugging Checklist

Before running at load, validate your simulation with this quick checklist:
  1. Run with atOnceUsers(1) — confirm the full user journey completes without errors.
  2. Enable TRACE logging — visually verify request/response pairs.
  3. Print key session values — confirm feeders inject the expected data.
  4. Check assertions pass at 1 user — ensure your checks are correctly targeting the response structure.
  5. Remove all println calls — clean up before ramping up users.
  6. Switch to DEBUG logging — quieter output, only failures shown.

Build docs developers (and LLMs) love

Get started for freeTalk to us