« Back to Frequently Asked Questions

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:

StateExit codeMeaning
active1service is running
failed0service has failed
inactive1service 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

Learn more about systemctl

This article uses the systemctl command to achieve its tasks. For this popular tool there is a cheat sheet available!

» Mastering the tool: systemctl

systemctl cheat sheet

Feedback

Small picture of Michael Boelen

This article has been written by our Linux security expert Michael Boelen. With focus on creating high-quality articles and relevant examples, he wants to improve the field of Linux security. No more web full of copy-pasted blog posts.

Discovered outdated information or have a question? Share your thoughts. Thanks for your contribution.

Mastodon icon