How to show failed units with systemctl
Systemd units typically fail when something in the execution of a service does not go as planned. Another option is that a specific condition is not met. Instead to continue running the service, it then can also be marked as failed. In this How To we look at how to show failed units.
Showing failed units
The shortest option to get information about units that failed is using the --failed option.
systemctl --failed
If all is well, then the output may look like this:
# systemctl list-units --state=failed
UNIT LOAD ACTIVE SUB DESCRIPTION
0 loaded units listed.
If a service has failed, then it will show the unit(s) and also the total count (last line).
UNIT LOAD ACTIVE SUB DESCRIPTION
● my-failed-service.service loaded failed failed Failure test
LOAD = Reflects whether the unit definition was properly loaded.
ACTIVE = The high-level unit activation state, i.e. generalization of SUB.
SUB = The low-level unit activation state, values depend on unit type.
1 loaded units listed.
Aliases that do the same as --failed include:
- systemctl list-units --state=failed
- systemctl list-units --failed
Testing if a unit has failed
For some service it may be interesting to monitor them, especially if they have a higher chance of failing. To test if a unit has failed, we can use the is-failed command.
systemctl is-failed ssh.service
The command will return a single line with the state:
| State | Exit code | Meaning |
|---|---|---|
| active | 1 | service is running |
| failed | 0 | service has failed |
| inactive | 1 | service is not active |
The exit code is useful for shell scripting. Use it in combination with the --quiet option to silence the output.
if systemctl is-failed --quiet my-failed-service; then
echo "My service failed"
fi