highFoundationSymptom-first#port#bind#socket#listen#address

Address already in use — port binding conflict

bind: Address already in use error on application startup

Likely source:availabilityconfiguration

Focused incident mode — strips away everything but this runbook.

Symptoms

  • bind: Address already in use error on application startup
  • Service fails to start after a crash without cleanup
  • Multiple services compete for the same port

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Listening ports

    ss -ltnp | grep :<PORT>

  • Process using the port

    ss -ltnp sport = :<PORT>

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • ss shows the old PID (now dead or zombie) still holding the port
  • Application was force-killed (SIGKILL) without port cleanup

Confirm before fixing

ss -ltnp sport = :<PORT>
READ

Confirm the stale process is the old instance

Fix

kill -9 <stale-PID>
DESTRUCTIVE

Force-kill the stale process to release the port

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
ss -ltnp | grep :<PORT>
READ

Find who holds the port

2
ps -p <PID> -o pid,ppid,cmd
READ

Identify the process

3
kill -TERM <PID>
CHANGE

Stop the process gracefully

4
sleep 2 && ss -ltnp | grep :<PORT>
READ

Verify the port is free

Prevention

  • Set SO_REUSEADDR in applications that need to restart quickly.
  • Use systemd socket activation to have systemd manage port binding.
  • Monitor port conflicts with a cron check on ss output.
  • Configure services with unique default ports to avoid collisions.

Related runbooks

Same stack, same failure family — worth a skim.

TCP TIME_WAIT socket exhaustion — ephemeral port exhaustionhigh

Cannot assign requested address errors when connecting out

LinuxAdvancedUSE2 causes
Open runbook
Systemd service fails to start — unit enters failed statehigh

systemctl status <service> shows failed state

LinuxFoundation3 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.