systemctl-is-failed

Check if there are any failed units

$ systemctl is-failed

$ systemctl is-failed [unit1 unit2 ...]

$ systemctl is-failed [unit] [[-q|--quiet]]

$ systemctl is-failed [unit] --user

systemctl [OPTIONS...] is-failed [UNIT...]

-h, --help
    Show a short help text and exit.

--system
    Connect to the systemd system manager. This is the default.

--user
    Connect to the systemd user session manager.

-q, --quiet
    Suppress output. Only the exit code indicates the success or failure of the operation. Essential for scripting.

-t, --type=TYPE
    When no UNIT is specified, filter units by type (e.g., 'service', 'socket').

--root=PATH
    Operate on a specified root directory, useful for chroot/container environments.

systemctl is-failed is a crucial subcommand of the systemctl utility, designed to query the current failure state of one or more systemd units. A unit is deemed 'failed' if its most recent activation attempt was unsuccessful, or if it exited with an error status. This command is particularly valuable for automation, scripting, and monitoring tasks, as its exit code directly communicates the unit's state.

When invoked with a specific unit name (e.g., sshd.service), it will check that unit's 'ActiveState'. If the unit's state is 'failed', the command exits with a status code of 0. If the unit is active, inactive, or in any other state that is not 'failed', it exits with a status code of 1. Other exit codes (typically >1) indicate an error, such as an unknown unit name. Its concise output (usually just 'failed', 'active', 'inactive', etc., or nothing with --quiet) combined with its robust exit code mechanism makes it ideal for conditional logic within shell scripts to react to service failures.

systemctl is-failed reflects only the current state. A unit could have failed previously and then been successfully restarted, in which case is-failed would report it as not failed. It requires appropriate permissions; typically, checking system units requires root privileges or sudo.

The primary mechanism for its use in scripts is its exit code. Relying solely on its textual output can be less robust.

The exit code of systemctl is-failed is its most important feature for scripting:
0: The specified unit is in a 'failed' state.
1: The specified unit is not in a 'failed' state (it could be 'active', 'inactive', 'activating', 'deactivating', etc.).
>1: An error occurred (e.g., the specified unit does not exist, or insufficient permissions).

This command is frequently used in shell scripts for conditional execution based on service health, for example:
if systemctl is-failed myapp.service &> /dev/null;
then
echo "myapp.service is failed! Restarting..."
sudo systemctl restart myapp.service
elif ! systemctl is-active myapp.service &> /dev/null;
then
echo "myapp.service is not active! Starting..."
sudo systemctl start myapp.service
else
echo "myapp.service is running correctly."
fi

Note the use of &> /dev/null with --quiet for clean script output, relying only on the exit code.

The systemctl is-failed command is an integral part of systemd, which was initially released in 2010 and has progressively become the default init system for most major Linux distributions, replacing older systems like SysVinit and Upstart. The is-failed subcommand was introduced early in systemd's development as a fundamental tool for programmatically querying the health of units, highlighting systemd's focus on robust service management and automation capabilities. Its design as a simple exit-code-driven checker reflects the broader Unix philosophy of 'do one thing well' for easy integration into shell scripts and other automation tools.

systemctl(1), systemctl status(1), journalctl(1), systemd.unit(5), systemd(1)