Address already in use (EADDRINUSE)
ID: networking/address-already-in-use
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| any | active | — | — | — |
Root Cause
A process attempted to bind a socket to an address:port combination that is already in use by another process. This commonly occurs when restarting a server that did not cleanly release its socket, or when multiple instances of the same service are launched.
genericWorkarounds
-
93% success Identify and stop the process using the port, then set SO_REUSEADDR
1. Find what is using the port: ss -tlnp | grep :PORT or lsof -i :PORT 2. If it is a stale process, kill it: kill PID (then kill -9 PID if needed) 3. If the port is in TIME_WAIT, set SO_REUSEADDR on the server socket before bind() 4. In most frameworks this is a configuration option (e.g., reuseaddr=True) 5. Restart your service 6. Verify: ss -tlnp | grep :PORT shows your new process
-
88% success Wait for TIME_WAIT to expire or enable SO_REUSEPORT for load balancing
1. Check if the port is in TIME_WAIT: ss -tan | grep :PORT 2. If TIME_WAIT, wait ~60 seconds for it to clear, or: 3. Set SO_REUSEADDR on the socket: setsockopt(SOL_SOCKET, SO_REUSEADDR, 1) 4. For multiple instances sharing a port, use SO_REUSEPORT: setsockopt(SOL_SOCKET, SO_REUSEPORT, 1) 5. To reduce TIME_WAIT duration system-wide: sysctl -w net.ipv4.tcp_fin_timeout=30 6. Enable tcp_tw_reuse for outbound connections: sysctl -w net.ipv4.tcp_tw_reuse=1
Dead Ends
Common approaches that don't work:
-
Kill all processes and hope the port is released
65% fail
Blindly killing processes can terminate unrelated critical services. If the port is in TIME_WAIT state from a recently closed connection, killing processes will not help because no process holds the port -- the kernel holds it for the TCP TIME_WAIT period (typically 60 seconds).
-
Immediately change to a different port number to avoid the conflict
70% fail
This avoids the immediate error but does not fix the root cause. The original port may be required by clients, load balancers, or firewalls. If the stale process is still running on the original port, it will continue consuming resources and potentially serving stale responses.