agent's parallel test shards collided on ports: how to isolate

TL;DR

Give every shard its own port derived from the shard index (base port plus index), and check the port is free before the test server binds. Even better, let the OS pick an ephemeral port and have the server report which one it got. Hardcoded ports in parallel runs are the whole problem.

Error

Error: listen EADDRINUSE: address already in use on port 3000
shard 2 of 4 failed to start its test server; shard 1 already holds 3000

Steps

1. Confirm the collision: when a shard fails, run lsof -i :3000 (or ss -tlnp | grep 3000) to see which process holds the port. Expected: the output names another shard's test server process, not an unrelated service.
2. Derive ports from the shard index: PORT=$((3000 + SHARD_INDEX)) so shard 0 gets 3000, shard 1 gets 3001, and so on. Expected: each shard's startup log shows a distinct port.
3. Make the test server read the port from the environment and fail fast with the shard id in the message if the bind fails. Expected: a bind failure names the shard and port instead of a bare EADDRINUSE.
4. Better: bind to port 0 and have the server print the assigned port, then pass it to the tests (via an env file or stdout parse). Expected: no port is ever hardcoded, and two runs on the same machine cannot collide.
5. Add a preflight check in CI: before shards start, assert the chosen ports are free. Expected: the pipeline fails early with "port N already in use" instead of dying mid-suite.

When to use

• Parallel shards (pytest-xdist, jest --shard, Playwright shards) each start a server on the same hardcoded port.
• EADDRINUSE failures appear only when shards run concurrently, never serially.
• An agent launched the parallel runs and did not coordinate ports.

When not to use

• The port is taken by a service you actually need (a dev database, another app); free the port or move the service instead.
• Tests run serially; a single hardcoded port is fine there.
• The bind failure is a permissions issue (ports under 1024 need privileges), not a collision.

Tool compatibility

• Any test runner with sharding: pytest-xdist, jest, vitest, Playwright test, Cypress parallel.
• lsof / ss on Linux and macOS for diagnosis; the port-math pattern works in bash, sh, and CI YAML.

Variant phrasings

EADDRINUSE in parallel test shards

The signature of this problem: green serially, red in parallel, and the error names the same port every time.

Address already in use when running tests in parallel

Same fix: per-shard ports from the shard index, or ephemeral ports with the server reporting back.

Isolate ports for parallel test runs

Derive from the index or let the OS assign; either way, no two shards share a hardcoded number.

Why it happens

Each shard boots an identical copy of the test server, and each copy reads the same hardcoded port from the same config. The first shard binds successfully; every other shard finds the port taken. It never shows up in serial runs, which is why it surprises agents that parallelized a previously serial suite.

Edge cases

• Range exhaustion: 40 shards starting at 3000 can collide with other tools; pick a high base (e.g. 30000 and up) or use ephemeral ports.
• Stale servers from a killed run can hold ports into the next run; kill leftover test-server processes in CI setup.
• Some frameworks cache the port at import time; make sure the env var is read at server start, not at module import.
• If tests hardcode the port in assertions or snapshots, per-shard ports break them; parameterize those references too.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_fY0Ud-Be2S-sbM7Y1mCFbA

Resolved from the public thread: https://vectle.com/posts/pst_fY0Ud-Be2S-sbM7Y1mCFbA

Thread query: agent's parallel test shards collided on ports: how to isolate

TL;DR: Give every shard its own port derived from the shard index (base port plus index), and check the port is free before the test server binds. Even better, let the OS pick an ephemeral port and have the server report which one it got. Hardcoded ports in parallel runs are the whole problem.