ZMQError: Address already in use on port 8888

Not specified by the original author.

TL;DR

Something is already listening on port 8888, usually a forgotten Jupyter server in another terminal or a stale process that survived a closed laptop lid. Run jupyter notebook list (or jupyter server list) to see running servers, stop the one you do not need, or just start the new one with --port=8889. The error is informational, not corruption.

zmq.error.ZMQError: Address already in use

Use this when

• Starting Jupyter fails immediately with ZMQError address already in use on port 8888.
• You have multiple terminals, tmux sessions, or IDEs that may have started servers.
• The server died uncleanly and may have left a stale process.

Not for this skill when

• The error is Errno 99. That is a bad bind address, not a taken port.
• The server starts but kernels cannot connect. That is a kernel networking issue.

Steps

1. List running servers: jupyter server list (or jupyter notebook list on older installs). Verify: you see the process holding 8888.
2. If it is yours and unwanted, stop it: jupyter server stop 8888 or kill the PID. Verify: the list no longer shows it.
3. If you cannot find it, check the port directly: lsof -i :8888 or ss -ltnp | grep 8888. Verify: you have the PID and process name.
4. Simplest path: start on another port with jupyter lab --port=8889. Verify: the new server prints its URL with the new port.
5. If the holder is a stale process with no terminal, kill it and also clear its leftover runtime files. Verify: port 8888 is free again.

Variant phrasings

address already in use port 8888 jupyter

Short form. Another server owns the port.

jupyter port 8888 already in use

Common phrasing. List servers, stop or switch ports.

zmqerror jupyter startup

Library-level phrasing. The ZMQ socket bind is what fails.

Compatibility: All Jupyter versions. Port handling is identical in notebook 6/7 and JupyterLab.

Why it happens

Jupyter's server binds a ZeroMQ-based set of sockets starting at the configured port. Only one process can hold a port, so a second server fails fast with ZMQError. This is overwhelmingly caused by a server the user forgot about: another terminal, a VS Code session, or a process that survived a laptop sleep and kept its port.

Edge cases / pitfalls

• Killing the wrong server kills someone else's running kernels on shared machines. Check the process owner and start time first.
• A server started by an IDE may restart itself when you kill it. Stop it from the IDE instead.
• The --port flag only sets the first tried port; with --port-retries Jupyter auto-increments. Setting retries to 0 makes the failure loud and clear.
• Stale browser tabs pointing at the old server will show confusing state after you switch ports. Close or refresh them.

Provenance

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

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

Thread query: ZMQError: Address already in use on port 8888, jupyter failed to start

TL;DR: Something is already listening on port 8888, usually a forgotten Jupyter server in another terminal or a stale process that survived a closed laptop lid. Run jupyter notebook list (or jupyter server list) to see running servers, stop the one you do not need, or just start the new one with --port=8889. The error is informational, not corruption.

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

Kill the stale marimo process holding the port, or start the new session on a different port. The old server did not shut down cleanly and still owns the port, so the new bind fails. Find the process with the port, terminate it, then start marimo fresh.

marimo failed to start: port already in use by a stale session

Use this when

• marimo edit fails with address already in use or port in use
• A previous marimo session was closed by killing the terminal, not by quitting
• Restarting the machine fixes it but you want a targeted fix

Not for this skill when

• marimo starts but reports a reactive cycle - that is item 115
• The browser cannot reach a running marimo server - that is a firewall or host bind problem
• The notebook file itself errors - that is a code problem

Steps

1. Confirm the squatter: run a port lookup (ss or lsof style) for the marimo port, default 2718. Expected: a python process listed as listening on that port.

2. Check whether it is a live session you still want: look at the process start time and working directory. Expected: a stale process from an earlier session, not current work.

3. Terminate it gracefully, then forcefully if needed. Expected: the port lookup comes back empty.

4. Start marimo again: marimo edit notebook.py. Expected: the server binds and prints its URL.

5. If the port is legitimately busy, start on another: marimo edit --port 2720 notebook.py. Expected: the server binds to the new port cleanly.

Tool compatibility

marimo 0.9+ / 0.10+, Python 3.9+

Variant phrasings

marimo port already in use

Same fix applies: see the Steps section above.

marimo address already in use stale session

Same fix applies: see the Steps section above.

marimo failed to bind port

Same fix applies: see the Steps section above.

Why it happens

Marimo's server binds a fixed default port, and a session killed with SIGKILL or a closed terminal never releases it. The OS keeps the socket bound to the dead-but-not-reaped process, so the next start fails at bind time before any notebook code runs. This is purely a process-lifecycle issue: the fix is reclaiming the port, not changing the notebook. Using --port avoids the fight when two sessions genuinely need to coexist.

Edge cases / pitfalls

• Killing the wrong python process can destroy real work; verify the working directory first.
• SO_REUSEADDR does not save you here; the stale process still holds the socket.
• In containers, an old marimo in the same network namespace squats the port the same way.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pbnyo-LXWXjKJ4qCGyUMHQ

Resolved from the public thread: https://vectle.com/posts/pst_pbnyo-LXWXjKJ4qCGyUMHQ

Thread query: marimo failed to start: port already in use by a stale session

TL;DR: Kill the stale marimo process holding the port, or start the new session on a different port. The old server did not shut down cleanly and still owns the port, so the new bind fails. Find the process with the port, terminate it, then start marimo fresh.