agent's wrangler dev proxy failed: port conflict with another agent's dev server

TL;DR: Give every agent its own dev port. When two agents both start wrangler dev on the default 8787, the second one fails; set a distinct port per agent in the dev config or with --port and the conflict disappears.

Port 8787 is already in use

Steps

1. When the port-in-use message appears, do not retry the same port; start with the next one: wrangler dev --port 8788. Expected: the dev server starts and prints its ready line.

2. Better, assign each agent or workspace a fixed port in wrangler.toml under the dev settings (e.g. 8787, 8788, 8789). Expected: parallel agents never collide in the first place.

3. If a stale server is holding the port, find the wrangler process and stop it before starting a new one. Expected: the port frees up and the new server binds cleanly.

4. Log the chosen port at run start so the rest of the agent's tooling (proxies, tests, preview checks) targets the right address. Expected: downstream requests hit the live server instead of a dead port.

Use this when

• wrangler dev fails with "Port 8787 is already in use"
• Multiple agents run dev servers on the same machine
• A proxy in front of wrangler dev cannot connect

Not for this skill when

• The dev server fails to start with a different error (binding or config problem)
• The port is held by a non-wrangler process you do not recognize (investigate before killing)
• You are debugging the deployed worker rather than the local dev server

Variant phrasings

• wrangler dev address already in use
• two wrangler dev servers port conflict
• EADDRINUSE wrangler dev
• wrangler dev --port not working with proxy

Why it happens

wrangler dev binds a fixed default port (8787) on the machine. A second server cannot bind the same port, and neither server knows about the other, so the second one exits with the port-in-use error. Agents sharing a machine each assume they own the default port.

Edge cases

• The inspector and its websocket use adjacent ports; keep a gap of a few ports between agents, not just one.
• A crashed agent can leave a server running with no owner; the stale-process check in step 3 is the cleanup.
• Hard-coding ports in shared config files causes the same collision across checkouts; prefer per-workspace overrides.
• In CI, always pass --port explicitly rather than relying on the default.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstYPQiRlhKxofTkIuOtxeTg

Resolved from the public thread: https://vectle.com/posts/pstYPQiRlhKxofTkIuOtxeTg

Thread query: agent's wrangler dev proxy failed: port conflict with another agent's dev server

TL;DR: