systemctl exit codes: is-active, is-enabled, is-failed, and what LSB code 3 means

What it is

systemctl mixes two different exit-code conventions depending on the subcommand:

Subcommand	0 means	non-zero means
is-active PATTERN	at least one matching unit is active	none of them are: 3 if inactive, 4 if unknown (prints the state unless --quiet)
is-failed PATTERN	at least one matching unit is in the "failed" state	none of them have failed (1; 4 if unknown)
is-enabled UNIT	enabled, or "static", "indirect", "generated", "alias"	e.g. "linked", "masked", "disabled"; "not-found" gives 4
status [PATTERN|PID]	unit is active	follows the older LSB table below

For systemctl status (and other LSB-style checks), systemctl's manual states it "uses the return codes defined by LSB, as defined in LSB 3.0.0":

Value	LSB meaning	systemd's use
0	program is running / service OK	unit is active
1	program is dead, /var/run pid file exists	unit not failed (used by is-failed)
2	program is dead, /var/lock lock file exists	unused
3	program is not running	unit is not active
4	program or service status is unknown	no such unit

The manual adds an explicit caution: "The mapping of LSB service states to systemd unit states is imperfect, so it is better to not rely on those return values but to look for specific unit states and substates instead."

Why it matters

LSB code 3 ("not running") is not an execution error — it is systemctl successfully telling you the service is simply stopped, which is a completely valid, common state (a oneshot unit, a disabled service, a unit intentionally stopped for maintenance). Treating any non-zero systemctl exit as "the systemctl invocation broke" will alarm on a routine "it's just off" answer.

How to apply

• Use is-active/is-failed/is-enabled for scripted checks rather than parsing status output — each has a documented, narrow 0-vs-non-zero meaning.
• Use --quiet with is-active/is-enabled/is-failed to suppress the printed state and rely purely on the exit code in scripts.
• When you do rely on the LSB table (e.g. from an older init-script wrapper), remember 3 means not active — which includes a failed unit, so use is-failed to tell stopped from crashed — and 4 means "systemd doesn't know this unit exists" (typo, unit file missing).
• Prefer systemctl show -p ActiveState,SubState <unit> for anything beyond a simple boolean check, in line with the manual's advice.

Pitfalls

• Assuming a non-zero from is-active is always 1: current systemd (e.g. 255) returns 3 for an inactive unit and 4 for an unknown one, while is-failed returns 1 for "not failed".
• Alerting on any non-zero from systemctl status <unit> in a monitoring script without checking whether the value is simply 3 (stopped).