Diagnose a systemd unit that failed to start
A clean, generic diagnostic path with no version-sensitive claims to get wrong: systemctl --failed (system and user), journalctl -b -u / --user-unit, -p err..alert, systemctl cat/show, journalctl -b _PID= for short-lived units, reset-failed, and 'never edit units under /usr/lib, use systemctl edit'. The Sunshine example is verified against the cited source: basecamp/omarchy#8582 exists and shows pacman -Ql sunshine listing /usr/lib/systemd/user/app-dev.lizardbyte.app.Sunshine.service while omarchy-install-service-sunshine runs systemctl --user enable --now sunshine, the exact name mismatch the record describes. pacman -Ql <package> | grep '\.service$' is the right habit to teach.
Symptom
Something silently does not work after boot. systemctl status foo says Active: failed (Result: exit-code) or the boot prints Failed to start <something>. See 'systemctl status ...' for details. Or an installer script aborted with Failed to enable unit: Unit foo.service could not be found.
Cause
Generic, but the diagnostic path is always the same, and most people never get past systemctl status, which truncates the log to a handful of lines. The "could not be found" variant is usually a script guessing a unit name that does not match what the package actually ships (e.g. Sunshine ships app-dev.lizardbyte.app.Sunshine.service, not sunshine.service).
Fix
List everything that is broken first:
systemctl --failed
systemctl --user --failed
systemctl status <unit>
Read the unit's full log for the current boot:
journalctl -b -u <unit> --no-pager
journalctl --user-unit <unit> --no-pager # user units
Errors only, across the whole boot:
journalctl -b -p err..alert --no-pager
Inspect what the unit actually runs and what it inherits:
systemctl cat <unit>
systemctl show <unit> -p ExecStart -p Environment
If a unit "could not be found", never guess the name. Ask the package:
pacman -Ql <package> | grep -E '\.service$'
systemctl --user list-unit-files | grep -i <name>
For a short-lived service that logs nothing under its unit name, find the PID from the status output and query by PID instead, because unit attribution is racy for processes that exit immediately:
journalctl -b _PID=123
After fixing, clear the failed state:
sudo systemctl reset-failed <unit>
sudo systemctl daemon-reload
sudo systemctl restart <unit>
Never edit unit files under /usr/lib/systemd/, because package updates overwrite them. Use sudo systemctl edit <unit> instead.
Verify
systemctl --failed returns 0 loaded units listed, and systemctl is-active <unit> prints active.