"Address already in use" errors occur when a service tries to bind to a port that's already occupied by another process. This guide covers diagnosing and resolving this common startup error.
What This Error Means
Only one process can bind to (listen on) a specific port at a time — this error occurs when a service attempts to start on a port already claimed by another running process.
Step 1 — Identify What's Using the Port
sudo ss -tulnp | grep :PORT_NUMBERsudo lsof -i :PORT_NUMBERShows the process ID and name currently bound to the specified port.
Step 2 — Determine If It's the Same Service (A Leftover Process)
Often, the "conflicting" process is actually a previous, still-running instance of the same service you're trying to start — common after a crashed restart that didn't fully clean up the previous process.
Step 3 — Stop the Conflicting Process (If Appropriate)
sudo kill PIDIf it's genuinely an old/leftover instance of the same service, terminate it and then start the service normally.
Step 4 — If It's a Genuinely Different Service
Decide whether to stop the other service (if it shouldn't actually be running), or reconfigure one of the two services to use a different port — two services genuinely needing the same port simultaneously requires one of them to change.
Common Scenario: Restarting a Service That Didn't Fully Stop
sudo systemctl status nginxCheck if the service manager already considers it running — if so, use restart rather than start, or stop it explicitly first before attempting a fresh start.
Common Scenario: A Docker Container Using the Port
docker psIf a Docker container has already claimed the host port you're trying to use, either stop that container or reconfigure one of the conflicting services to use a different port mapping.
Checking If the Port Is in TIME_WAIT State (A Different, Related Issue)
ss -tan | grep :PORT_NUMBERA port briefly in TIME_WAIT after a connection closes isn't quite the same as "in use" by a listening process, but can sometimes cause confusion; this state resolves itself after a short timeout without intervention needed.
Allowing Socket Reuse (For Development, Use Cautiously in Production)
sudo sysctl -w net.ipv4.tcp_tw_reuse=1Allows faster socket reuse in specific TIME_WAIT scenarios — understand the implications before applying broadly in production, since this affects TCP behavior system-wide.
Preventing This from Recurring
Ensure services shut down cleanly (proper stop procedures, not force-killing unless necessary) and use process managers/systemd properly (see How to Manage Services with systemd and systemctl) rather than manually starting services in ways that can leave orphaned processes.
Common Errors
Port shows as free but the service still won't bind — verify you're checking with sufficient privileges (some checks need sudo) and that you're checking the exact correct port number the service is actually trying to use.
Continue Reading
- How to Manage Services with systemd and systemctl
- How to Debug a Failing Docker Container
- How to Fix Common Nginx Errors (502/504/403)
Browse more articles in Troubleshooting & FAQ.
