wrangler dev: Port 8787 is already in use

Not specified by the original author.

TL;DR: Something is already listening on 8787, usually a previous wrangler dev that did not exit. Find the process and stop it, or start this session on another port with the port flag. The error is about the port, never about your code.

wrangler dev: "Port 8787 is already in use"

1. Confirm what holds the port. Run:

   lsof -i :8787

   Expected: one or more lines showing the process name and PID. A node or workerd process means a stale wrangler dev.

2. If it is a stale wrangler dev you no longer need, stop it:

   kill PID

   using the PID from step 1. If it ignores the kill, use kill -9 on the PID. Expected: a repeat of the lsof command shows nothing listening.

3. Start wrangler dev again:

   wrangler dev

   Expected: the dev server starts and prints the local URL it is listening on.

4. If you need both sessions running, give this one a different port:

   wrangler dev --port 8788

   Expected: the dev server starts on 8788 and prints that URL.

5. If the port is held by something you do not recognize, check for duplicate terminal tabs or an editor extension that auto-starts wrangler. Expected: you find the launcher and can stop it from the source instead of killing it every time.

Use this when

• wrangler dev exits immediately with the port-in-use message
• a previous dev session was closed by killing the terminal instead of quitting cleanly
• two projects need local dev servers at the same time
• CI or a script starts wrangler dev and a previous run is still alive

Not for this skill when

• wrangler dev starts but the worker code fails (that is a code or binding error)
• the error is about the inspector port rather than 8787
• the dev server starts but requests hang (that is a worker logic problem)
• you cannot bind any port at all (that is a machine-level networking problem)

Variant phrasings

• wrangler dev port already in use
• "Port 8787 is already in use" cloudflare
• cannot start wrangler dev port taken
• workerd port 8787 conflict
• wrangler dev address already in use

Why it happens

Only one process can listen on a port at a time. wrangler dev binds 8787 for the local worker, and if a previous session is still alive, perhaps orphaned when its terminal was killed, the new session cannot bind it and exits with this message. It looks like a wrangler bug but it is the operating system refusing the second bind.

Edge cases

• The inspector uses its own port. If you run two dev sessions you may need to set the inspector port too, or let wrangler pick.
• kill -9 on a workerd process can leave the local state directory locked. If dev misbehaves after the kill, remove the .wrangler state directory and start fresh.
• Some editors restart wrangler dev on file save through tasks. That can re-grab the port right after you free it. Check background tasks before assuming the kill failed.
• In containers, the conflicting process may be in another container sharing the network namespace. lsof inside your container will not see it.
• Choosing a fixed alternate port per project in your npm scripts avoids the whole dance when you routinely run two projects.

Provenance

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

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

Thread query: wrangler dev: "Port 8787 is already in use"

TL;DR:

Not specified by the original author.

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:

Not specified by the original author.

TL;DR

Since version 3.19.0 of wrangler was released we're no longer able to run wrangler dev --remote.

Steps

1. Since version 3.19.0 of wrangler was released we're no longer able to run wrangler dev --remote. It runs, but as soon as a page is viewed the following error is thrown:
2. [petebacondarwin (contributor)]: Underscores in worker names break TLS hostname verification (test_worker.subdomain.workers.dev fails the check), which breaks wrangler dev --remote and Miniflare fetches. Rename the worker to remove the underscore: do it in the Cloudflare dashboard (Workers -> Manage -> Rename Worker), not by renaming in wrangler.toml, which would orphan the old worker. zehawki confirmed the dashboard rename fixed it with no data loss.

When to use

You are seeing this: It runs, but as soon as a page is viewed the following error is thrown: Use this skill when you run into "🐛 BUG: Unable to run wrangler dev since version 3.19.0".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: 3.19.0. If you are on something much newer or older, the details may have shifted.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

In gh:cloudflare/workers-sdk#4921 (https://github.com/cloudflare/workers-sdk/issues/4921), the reporter ran into this: Since version 3.19.0 of wrangler was released we're no longer able to run wrangler dev --remote. It runs, but as soon as a page is viewed the following error is thrown: The verified resolution: [petebacondarwin (contributor)]: Underscores in worker names break TLS hostname verification (test_worker.subdomain.workers.dev fails the check), which breaks wrangler dev --remote and Miniflare fetches. Rename the worker to remove the underscore: do it in the Cloudflare dashboard (Workers -> Manage -> Rename Worker), not by renaming in wrangler.toml, which would orphan the old worker. zehawki confirmed the dashboard rename fixed it with no data loss.