Gatling maxConnectionsPerHost: Determining the Optimal Value for Production Workloads

Direct answer

There is no universal optimal maxConnectionsPerHost. The right value is the smallest number that covers your peak concurrently active virtual users multiplied by maxConnectionsPerUser, while staying below the load generator's OS socket ceiling and the target server's connection capacity.

Why the default is often too low

Gatling's HTTP connection pool is per-host and shared across all virtual users. When the host limit is reached, additional users block until a connection is released. The default of 20 works for low-concurrency local tests, but if you inject 200 active users and each user needs 2 connections, the host pool becomes an artificial bottleneck regardless of your injection rate.

Scaling with virtual users

Scale the limit proportionally to concurrently active users, not total injected users. A practical starting formula is:

maxConnectionsPerHost ≈ active_virtual_users × maxConnectionsPerUser

Raise it only if the load generator can sustain that many sockets and the target infrastructure can accept them. If the target cannot, adjust the injection profile instead of the pool size.

OS-level exhaustion and detection

Increasing the host limit requires raising the load generator's file-descriptor limit. On long-running tests, ephemeral port exhaustion and TIME_WAIT accumulation can also bind before file descriptors run out. Gatling rarely emits an explicit pool-exhaustion error; instead you will see java.net.SocketException: Too many open files, connection timeouts, or unexpected resets.

Verify the generator's limits before a smoke test:

ulimit -n
ulimit -Hn

During the run, compare established connections against the configured limit:

ss -tan state established | grep <target_port> | wc -l

Inspect both Gatling logs and the target host's connection table for Too many open files, Connection refused, or Connection reset.

Validation

After raising the limit, confirm that achieved throughput and 95th-percentile response times improve. If they degrade, the bottleneck is likely the target server, not the injector.

Version note

This assumes Gatling 3.x with HOCON configuration. Property names and defaults can shift between releases; confirm the exact key in your version's gatling.conf before applying changes.

Missing diagnostic

To recommend a concrete number, what is your peak concurrently active virtual user count and your maxConnectionsPerUser setting? Without those two values, any specific figure would be a guess.