Articles

Fail Gatling Tests When SLA Thresholds Are Breached (2026)

April 18, 2026 6 min read

Gatling tests are failing because they’re hitting SLA thresholds, and you need to figure out why.

Common Causes and Fixes

1. Under-provisioned Load Generator Resources

  • Diagnosis: On your Gatling load generator (e.g., a Docker container or VM), check CPU, memory, and network I/O.
    • CPU: docker stats <container_id> or top on a VM. Look for sustained 90%+ CPU usage.
    • Memory: docker stats <container_id> or free -h on a VM. Check for excessive swap usage or low available memory.
    • Network: iftop -i <interface> on a VM. See if your network interface is saturated.
  • Fix:
    • Docker: Increase resource limits in your docker-compose.yml or docker run command. For example, to allocate 4 cores and 8GB RAM:
      services:
  gatling:
    image: akamai/gatling
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
        reservations:
          cpus: '2'
          memory: 4G
    # ... other configurations
    • VM: Adjust CPU/memory allocations in your hypervisor (e.g., vSphere, AWS EC2 instance type).
  • Why it works: Gatling itself consumes significant CPU and memory to manage thousands of concurrent virtual users and their states. If the load generator can’t keep up, it drops packets, introduces latency, and fails to send requests in time, leading to SLA breaches.

2. Insufficient Network Bandwidth from Load Generator

  • Diagnosis: Even with low CPU/memory, a saturated network interface on the load generator can be the bottleneck. Use iftop -i <interface> (e.g., eth0) on the load generator VM to see real-time bandwidth usage. If it’s consistently near the interface’s limit (e.g., 1 Gbps or 10 Gbps), this is your problem.
  • Fix:
    • Scale out load generators: Run more Gatling instances on separate machines/containers, distributing the load.
    • Upgrade network interface: If running on bare metal or a dedicated VM, ensure you have a sufficiently high-bandwidth network interface.
    • Cloud: Choose instance types with better network performance (e.g., "enhanced networking" on AWS).
  • Why it works: High throughput of requests requires high network bandwidth. If the load generator’s network egress is capped, requests will queue up or be dropped, delaying responses and failing SLA checks.

3. Target System Overload (Not Gatling’s Fault)

  • Diagnosis: This is the most common scenario. The Gatling test is correctly revealing that your application under test cannot handle the load.
    • Application Logs: Check your application servers for errors, high thread counts, excessive garbage collection pauses, database connection pool exhaustion, or slow query logs.
    • APM Tools: Use tools like Datadog, New Relic, or Dynatrace to identify bottlenecks in your application (e.g., slow downstream service calls, database contention, inefficient code).
    • Gatling Metrics: Examine Gatling’s response time percentiles (especially p95, p99). If they are high and consistently failing the mean or responseTime assertions, the target system is the culprit.
  • Fix: This is application-specific. Common fixes include:
    • Optimize application code: Improve algorithm efficiency, reduce redundant computations.
    • Tune database queries: Add indexes, rewrite slow queries.
    • Increase application instances: Scale horizontally by adding more application servers.
    • Tune application server settings: Adjust thread pool sizes, connection pools, JVM heap settings.
    • Address downstream dependencies: If your app calls other services, ensure they can handle the load.
  • Why it works: The SLA thresholds are designed to reflect acceptable performance for your users. If Gatling hits those thresholds and the application logs/APM data show stress, it means the application is genuinely performing poorly under the simulated load.

4. Incorrect Gatling Simulation Configuration

  • Diagnosis: Review your Gatling simulation code (.scala file).
    • constantUsersPerSec: Is the injection rate too high for the system to handle from the start?
    • rampUsersPerSec: Is the ramp-up too aggressive, overwhelming the system before it can stabilize?
    • atOnceUsers: Are you starting too many users simultaneously, causing an immediate spike that the system can’t absorb?
    • Assertions: Are your SLA assertions too strict for the current state of the application or infrastructure? For example, asserting responseTime.mean.lte(100) might be unrealistic if your average response time is consistently 200ms.
  • Fix:
    • Adjust Injection Profile:
      • Reduce constantUsersPerSec or rampUsersPerSec values.
      • Increase the rampTo duration for rampUsersPerSec.
      • Use atOnceUsers with caution, possibly combined with a gradual ramp.
      • Example: Instead of constantUsersPerSec(1000) during (60 seconds), try rampUsersPerSec(200) to (1000) during (5 minutes).
    • Adjust Assertions:
      • Temporarily relax assertions to see if the pattern of load is still causing issues, or if it was just the specific threshold.
      • Example: Change global.responseTime.mean.lte(100) to global.responseTime.mean.lte(250).
  • Why it works: The injection profile dictates how quickly load is applied. An overly aggressive profile can shock the system, leading to immediate performance degradation and SLA breaches, even if the system could eventually handle the sustained load. Similarly, overly strict assertions can cause false failures.

5. Network Latency Between Load Generator and Target System

  • Diagnosis:
    • Ping/Traceroute: From the load generator, run ping <target_ip> and traceroute <target_ip> to check baseline latency and identify hops with high latency.
    • Gatling Reports: Look at the response time distribution in the Gatling HTML report. If all requests show significantly higher latency than expected, and the target system itself shows no signs of overload, network latency is a strong candidate.
  • Fix:
    • Co-locate: Move load generators closer to the target system (e.g., same VPC, same availability zone, same data center).
    • Improve Network Path: Investigate network configurations, routing, and firewall rules between the environments.
    • Reduce Payload Size: If large requests/responses are contributing, optimize data transfer.
  • Why it works: Every millisecond of network latency adds directly to the observed response time. High latency can easily push average or percentile response times over SLA thresholds, even if the target system processes requests instantly.

6. Gatling JVM Issues (Less Common but Possible)

  • Diagnosis:
    • GC Logs: Enable Garbage Collection logging for the Gatling JVM (-XX:+PrintGCDetails -XX:+PrintGCTimeStamps -Xloggc:gc.log). Analyze gc.log for frequent, long GC pauses.
    • JMX Metrics: Monitor JVM heap usage, thread counts, and CPU usage via JMX.
    • OOM Errors: Check Gatling’s console output or logs for OutOfMemoryError.
  • Fix:
    • Increase Heap Size: Add -Xmx and -Xms flags to the Gatling JVM options. For example, -Xmx8g -Xms8g for 8GB heap.
    • Tune GC: Experiment with different Garbage Collectors (e.g., G1GC is often a good default).
    • Reduce User Count: If the heap is consistently maxed out, you might need more load generators or a more powerful machine.
  • Why it works: If the Gatling JVM itself is spending too much time in garbage collection or running out of memory, it cannot efficiently dispatch requests or process responses, leading to timeouts and SLA failures.

The next error you’ll likely hit after fixing these is a "Simulation ended with errors" message if your assertions are still too strict, or you might start seeing different bottlenecks appear as you resolve the current ones.

Want structured learning?

Take the full Gatling course →