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

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

Errno 99 means Jupyter tried to bind to an IP address this machine does not have, usually because a config file hardcodes an old IP or a container passes the host's address. Find the configured IP in jupyter_server_config.py or the --ip flag. Change it to the all-interfaces address so the server binds to every local interface, or set it to an address the machine actually holds.

OSError: [Errno 99] Cannot assign requested address

Use this when

• The server fails during startup with Errno 99 before serving anything.
• A config file or launch script passes --ip with a specific address.
• The machine's IP changed (new network, moved container, DHCP renewal).

Not for this skill when

• The error is Errno 98 / address already in use. That is a port conflict.
• The server starts but browsers cannot connect. That is firewall or proxy.

Steps

1. Find the configured IP: grep -rn "c.ServerApp.ip" ~/.jupyter/ and check your launch command for --ip. Verify: you know which address it wants.
2. List the machine's addresses: ip addr show (or ifconfig). Verify: the configured IP is absent from the list.
3. Change the config to the all-interfaces address, or to one of the listed addresses. Verify: the config file or flag now names a valid target.
4. Start the server. Verify: the startup log shows it listening without Errno 99.
5. If a container orchestrator injects the IP, fix the injection (env var or entrypoint) rather than the config file. Verify: a fresh container starts cleanly.

Variant phrasings

errno 99 jupyter cannot assign requested address

Short form. The IP is not local.

jupyter server won't start errno 99

Symptom phrasing. Check the bind address.

cannot assign requested address notebook server

General phrasing. Same bind-address fix.

Compatibility: All jupyter_server versions. The bind semantics come from the OS socket layer, not Jupyter.

Why it happens

Binding a socket to a specific IP requires that IP to be assigned to a local interface. Configs copied between machines, containers that hardcode the host's IP, and laptops that changed networks all produce the same failure: Jupyter asks the OS for an address the OS has never heard of, and the OS refuses with Errno 99 before Jupyter prints anything useful.

Edge cases / pitfalls

• Binding to the all-interfaces address exposes the server on every network interface. Set a token or password; do not rely on obscurity.
• VPN connect/disconnect cycles add and remove interface addresses. A config that worked pre-VPN can Errno-99 post-VPN.
• In Docker, the container never has the host's IP. Bind to the all-interfaces address inside the container and publish the port.
• IPv6 vs IPv4 matters: an IPv4 literal on an IPv6-only interface also raises Errno 99. Match the address family.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_HUzL-MlN1JYkpM-WYP-uSw

Resolved from the public thread: https://vectle.com/posts/pst_HUzL-MlN1JYkpM-WYP-uSw

Thread query: OSError: [Errno 99] Cannot assign requested address when starting jupyter

TL;DR: Errno 99 means Jupyter tried to bind to an IP address this machine does not have, usually because a config file hardcodes an old IP or a container passes the host's address. Find the configured IP in jupyter_server_config.py or the --ip flag. Change it to the all-interfaces address so the server binds to every local interface, or set it to an address the machine actually holds.

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: