Load generator "Address already in use" (BindException) in CI

A load-testing run fails with "Address already in use" when the generator (or a helper it starts, like a web UI or metrics port) tries to bind a port that another process already holds, or when the runner has exhausted ephemeral ports under high concurrency.

What this error means

The tool aborts with "java.net.BindException: Address already in use" or "bind: address already in use", often on the web UI/metrics port, or "cannot assign requested address" during a high-VU run.

java.net.BindException: Address already in use
	at sun.nio.ch.Net.bind0(Native Method)
Caused by: bind: address already in use

Common causes

A fixed port is already bound

A previous run, another service container, or a leftover process holds the web UI or metrics port the tool wants.

Ephemeral ports exhausted under load

At very high concurrency the generator uses up the local ephemeral port range, so new outbound sockets cannot be assigned.

How to fix it

Free or change the bound port

1. Run headless so no web UI port is opened, or pass a free port.
2. Ensure a prior run is not still holding the port in the same job.
3. For k6/Locust web ports, set an unused port explicitly.

locust --headless ...           # no web UI port
locust --web-port 8090 ...       # or pick a free port

Widen the ephemeral port range and reuse

For high-concurrency generators, enable address reuse and widen the local port range on the runner.

sysctl -w net.ipv4.ip_local_port_range="1024 65535"
sysctl -w net.ipv4.tcp_tw_reuse=1

How to prevent it

• Run load tools headless in CI so no fixed UI port is needed.
• Give any required port an explicitly free value.
• Widen the ephemeral port range for very high concurrency.

Related guides