Your Agent Won't Start. Something Is Still Bound to Its Port.
You check in after a scheduled start or an overnight run. The unit is enabled. The config looks right. But the job never came up, and the journal shows listen EADDRINUSE: address already in use, or OSError: [Errno 98] Address already in use, or bind: address already in use on a TCP port or a unix socket path. You SSH in and start it by hand, and it fails the same way. Or it works, but only after you kill a leftover process you had forgotten about.
Not every agent listens on a port. When yours does, or a helper that serves a local dashboard, webhook, or API does, this is what you see when the address is already taken. This guide covers how to confirm what still holds the port or socket, rule out the cousins, free it safely, keep one owner, and add a fail-closed preflight.
The errors you’ll actually see
Error: listen EADDRINUSE: address already in use 0.0.0.0:18789from a Node process (or another local port).OSError: [Errno 98] Address already in usefrom a Python helper.listen tcp :3000: bind: address already in usefrom a Go binary.Failed to listen on sockets: Address already in usefrom systemd itself, usually around a.socketunit.- The same bind error naming a unix socket path such as
/run/agent.sockor a path under/tmp. systemctl startexits non-zero andsystemctl statusshows the unit as failed.ssorlsofstill shows a listener after you thought you stopped the service.- Starting from an interactive shell also fails until a leftover PID is gone.
- The failure returns after a reboot, because a second unit or a
@rebootcron line races the systemd unit. - After a crash, a
.sockfile is still on disk even thoughssshows nothing listening on it.
Rule out the cousins first
- systemd gave up. If
systemctl statusonly saysstart-limit-hit, see the restart loop and start-limit post. A bind failure is often why the unit was looping, so runsystemctl reset-failed your-unitand read earlier journal lines forin use. - Two schedulers firing the same work. Two timers running the same job is the duplicate schedulers post. This post is about leftover or duplicate listeners on the same port or socket.
- Out of file descriptors. If the process cannot create a socket at all, the error is
EMFILEorToo many open files, notEADDRINUSE. See the EMFILE post. - Privileged port.
Permission deniedorEACCESwhen binding a port below 1024 means the job user is not allowed to bind it. Nothing else is using it. - Waiting on a prompt. A service that starts and then hangs on interactive input is a different failure with a different fix.
Why it hides
The unit looks stopped, but a copy you started by hand in an SSH session, or a child that double-forked, is still listening and is not in the unit’s cgroup, so systemctl stop never touched it. systemctl stop can also return while a process is still shutting down or ignoring SIGTERM.
A unix socket file survives a crash, so the next bind fails even though ss shows no listener. systemd socket activation may already hold the port while the app also tries to bind it. Two units, or a unit plus a crontab @reboot line, may both start the same binary. The port in the error may also not be the port in the file you edited, because the running unit can still carry an old Environment= line or a different env file.
TIME_WAIT from a recent close can block a quick restart if the server does not set address reuse. That is less common than a living leftover process, so check for a listener first.
Step 1: Confirm the address and what holds it
Take the exact listen address from the error. Then confirm what the unit is actually configured to use, so you are not inspecting the wrong number:
UNIT=your-agent.service
systemctl show "$UNIT" -p Environment -p EnvironmentFiles -p User
systemctl cat "$UNIT"
# Then read any EnvironmentFile= and the app config it points to.
For a TCP port, look for an existing listener. Run ss with sudo so it can show process names for other users:
PORT=18789
sudo ss -lptn "sport = :$PORT"
sudo ss -lptn | grep ":$PORT " # catches :: vs 0.0.0.0 on the same port
command -v lsof >/dev/null && sudo lsof -iTCP:"$PORT" -sTCP:LISTEN
For a unix socket:
SOCK=/run/agent.sock
sudo ss -lxpn | grep -F -- "$SOCK"
ls -l "$SOCK"
If a listener appears, record its details. This is diagnosis, not a kill:
PID=1234 # from the users:(("name",pid=...)) field
ps -o pid,user,etime -p "$PID"
tr '\0' ' ' < /proc/"$PID"/cmdline; echo
systemctl status "$PID" --no-pager | head -n 5
systemctl status PID names the unit that owns the process, or a session scope such as session-3.scope if it was started from an SSH login. If ss shows a listener, that process is why bind fails. If there is no listener but a socket file still exists, that leftover file is why bind fails.
Step 2: Free the address safely
If a unit owns the leftover process, stop it through systemd and recheck:
sudo systemctl stop the-owning-unit.service
sudo ss -lptn "sport = :$PORT"
If it is an orphan or a manual start, and the command line matches your agent, stop that one PID and give it time to exit:
kill "$PID" # SIGTERM first
sleep 10
sudo ss -lptn "sport = :$PORT"
# Only if it is still listening:
# kill -9 "$PID"
For a stale unix socket with no listener, remove only that path, and only after ss shows it is not bound:
sudo ss -lxpn | grep -F -- "$SOCK"
# If that printed nothing:
sudo rm -f "$SOCK"
Do not delete every .sock file on the box, run fuser -k on a port blindly, or start a second copy as root to get around the bind. And do not change the port as the standing fix: if a leftover process is the cause, that just leaves two copies running.
Then start the unit once and confirm it is the only listener:
sudo systemctl start "$UNIT"
sudo ss -lptn "sport = :$PORT" # exactly one line, owned by your unit's process
If ss shows no LISTEN, only TIME_WAIT, wait a minute, or turn on address reuse if the app already exposes that option.
Step 3: Make sure only one thing binds that address
- One starter. Do not start the agent from systemd and also from a crontab, a
@rebootline, or anohupin a tmux session. Check withcrontab -l,sudo crontab -l, andgrep -r your-agent /etc/cron* 2>/dev/null. - One unit. If two units point at the same binary and port, disable or correct the extra one:
systemctl list-units --all | grep -i agent. - Socket activation, or not. If you use a
.socketunit, the app should accept the already-open socket and not bind the same address again. If you do not use socket activation, do not also ship a.socketunit for that port. - Pin the address. Set the port or socket path in the unit’s
EnvironmentFile=or the app config, and point the preflight at the same file so they cannot drift. - Make stop actually stop. If the process sometimes ignores SIGTERM, set
TimeoutStopSec=so systemd escalates, and add a realExecStop=if the app needs one.systemctl stopshould leave the port free when it returns. - Keep runtime sockets in
/run. A tmp cleanup can race a restart for a socket under/tmp. UseRuntimeDirectory=agentand a path like/run/agent/agent.sock.
Step 4: A fail-closed preflight
The preflight reads the same env file as the service, fails if the port or socket is already taken or stale, logs one clear line, alerts once per outage, and exits 1. Give the job user a marker directory that clears on reboot:
echo 'd /run/agent-preflight 0755 agent agent -' | sudo tee /etc/tmpfiles.d/agent-preflight.conf
sudo systemd-tmpfiles --create /etc/tmpfiles.d/agent-preflight.conf
#!/usr/bin/env bash
# /usr/local/bin/agent-bind-preflight.sh
# Fail closed if the agent's listen address is already taken.
set -u
PORT="${AGENT_PORT:-18789}" # leave empty if the agent only uses a socket
SOCK="${AGENT_SOCK:-}" # e.g. /run/agent/agent.sock
NAME="${AGENT_NAME:-agent}"
MARKER="/run/agent-preflight/bind-alerted"
fail() {
local msg="$1"
logger -t agent-preflight "$msg"
echo "$msg" >&2
if [ -n "${DISCORD_WEBHOOK_URL:-}" ] && [ ! -e "$MARKER" ]; then
local safe
safe=$(printf '%s' "$msg" | tr -d '"\\')
curl -fsS -m 10 -H 'Content-Type: application/json' \
-d "{\"content\":\"$safe\"}" "$DISCORD_WEBHOOK_URL" >/dev/null 2>&1 \
&& touch "$MARKER"
fi
exit 1
}
owner() { # pid and command from an ss line, if visible to this user
local pid
pid=$(printf '%s' "$1" | grep -o 'pid=[0-9]*' | head -n1 | cut -d= -f2)
[ -n "$pid" ] && printf ' pid=%s cmd=%s' "$pid" "$(tr '\0' ' ' < /proc/"$pid"/cmdline 2>/dev/null)"
}
if [ -n "$PORT" ]; then
line=$(ss -Hlptn "sport = :$PORT" 2>/dev/null | head -n1)
[ -n "$line" ] && fail "$NAME preflight: TCP port $PORT already has a listener$(owner "$line")"
fi
if [ -n "$SOCK" ]; then
line=$(ss -Hlxpn 2>/dev/null | grep -F -- "$SOCK" | head -n1)
[ -n "$line" ] && fail "$NAME preflight: socket $SOCK already has a listener$(owner "$line")"
[ -e "$SOCK" ] && fail "$NAME preflight: stale socket file $SOCK exists with no listener"
fi
rm -f "$MARKER"
exit 0
As a non-root user, ss may hide the PID if another user owns the listener. The check still fails closed; it just names the port.
For a cron-driven start, chain it:
*/15 * * * * . /etc/agent/agent.env; /usr/local/bin/agent-bind-preflight.sh && /usr/local/bin/start-agent-job
As ExecStartPre= of the unit, it runs before the main process binds, so a leftover listener fails the start and a clean box passes:
[Service]
User=agent
EnvironmentFile=/etc/agent/agent.env
RuntimeDirectory=agent
ExecStartPre=/usr/local/bin/agent-bind-preflight.sh
ExecStart=/usr/local/bin/your-agent
TimeoutStopSec=20
Run it as the job user, or as ExecStartPre= of the User= service. If you use systemd socket activation, this preflight as written will false-fail because the .socket unit already holds the port, so do not use it as-is in that setup.
Standing routine
- Every start: the preflight runs and either passes silently or names the port, path, and PID.
- After adding a second unit, crontab line, or manual start method: confirm only one thing starts the agent, and that the preflight reads the same env file.
- After a crash or a forced kill: check
ssfor a leftover listener and the socket path for a stale file before restarting. - Monthly: run
sudo ss -lptnandsudo ss -lxpn, confirm exactly one listener on the agent’s address, and confirm the configured port still matches what the unit uses. Pair this with a stalled automation alarm so a start that fails closed does not go unnoticed.
If you already run the reboot and power-loss test, add one check: after the box comes back, there is exactly one listener on the configured port or socket. A box can return with two starters racing, or with a stale socket file on a persistent filesystem.
Address-in-use failures are rarely mysterious once you look at ss. The hard part is catching a forgotten copy, a second starter, or a stale socket before the next scheduled run. If you want the prompts and checklists we use to keep unattended agents honest, start with the free prompts, go deeper with the OpenClaw Agent Ops Toolkit, or get everything in the Ultimate Bundle.
More from the build log
Suggested
Want the full MarketMai stack?
Get the core MarketMai guides and operator playbooks in one premium bundle for $49.
View Bundle