Skip to content
Browse

/commands/systemd/systemctl-list-failed-units

systemctl --failed: list failed services and see why

The commands on this page have not been executed by our verification runner yet.updated
tool
systemd
versions
systemd 2xx
os
linux

systemctl --failed (short for systemctl list-units --state=failed) lists every unit that is in the failed state. For each one, systemctl status NAME shows the last log lines and the exit code, and journalctl -u NAME -b shows its full log since the last boot. After fixing the cause, systemctl reset-failed NAME clears the failed state.

List failed units

bash
systemctl --failed
systemctl list-units --state=failed --type=service   # services only
systemctl --user --failed                            # units of your user manager
systemctl is-failed nginx.service                    # prints "failed" and exits 0 if failed

Find out why a unit failed

bash
systemctl status nginx.service            # state, main PID, exit code, last 10 log lines
journalctl -u nginx.service -b            # all log lines for the unit since boot
journalctl -u nginx.service -n 50 --no-pager
journalctl -u nginx.service -f            # follow new lines
journalctl -xeu nginx.service             # jump to the end, with explanations

The Main PID line of systemctl status shows how the process ended, for example code=exited, status=1/FAILURE (the program exited with status 1) or code=killed, signal=KILL. Result: values such as exit-code, signal, timeout, core-dump and start-limit-hit tell you which rule marked the unit as failed.

Common results

ResultMeaningWhere to look
exit-codeThe main process exited with a non-zero statusThe program log: journalctl -u NAME
signalThe process was killed by a signalOOM killer messages: journalctl -k -b | grep -i oom
timeoutStart or stop took longer than TimeoutStartSec / TimeoutStopSecSlow start-up, or Type= does not match the program
start-limit-hitThe unit restarted too often (StartLimitBurst within StartLimitIntervalSec)The first failure in the log, then reset-failed
core-dumpThe process crashed and dumped corecoredumpctl list

After fixing it

bash
systemctl daemon-reload                 # only if you edited a unit file
systemctl reset-failed nginx.service    # clear the failed state and the start-limit counter
systemctl restart nginx.service
systemctl status nginx.service

Commands that change units (restart, reset-failed, daemon-reload) need root for system units: run them with sudo.

Sources

Related pages

cheat sheets · croncrontab syntax cheat sheet: * * * * * explainedCrontab syntax explained: the five time fields, ranges, lists and */n steps, @reboot and @daily strings, common schedules, and why jobs fail with a short PATH.errors · certbotCertbot: Problem binding to port 80: Could not bind to IPv4 or IPv6certbot --standalone fails with Problem binding to port 80 when nginx, Apache or another service already listens there. Use the webroot or nginx plugin instead.codes · bashBash exit codes: 0, 1, 2, 126, 127, 128+n and 255What bash exit codes mean: 0 success, 1 general error, 2 misuse of builtins, 126 not executable, 127 not found, 128+n killed by signal n, and how to read $?.commands · systemdsystemctl enable --now: start a service and enable it at bootsudo systemctl enable --now NAME starts a service now and at every boot; disable --now undoes it. is-enabled states, mask, and the errors enable can print.