highFoundationSymptom-first#systemd#service#unit#journalctl#start

Systemd service fails to start — unit enters failed state

systemctl status <service> shows failed state

Likely source:availabilityconfiguration

Focused incident mode — strips away everything but this runbook.

Symptoms

  • systemctl status <service> shows failed state
  • Application is not running after boot or restart
  • journalctl -u <service> shows error messages

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Service status

    systemctl status <service>

  • Service journal logs

    journalctl -u <service> --since '10 min ago' --no-pager

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • journalctl shows ConfigFile not found or parse error
  • Service was recently updated with a broken config

Confirm before fixing

systemctl cat <service>
READ

Show the unit file and ExecStart command

Fix

systemctl edit <service>
CHANGE

Fix the configuration file or unit override

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
systemctl status <service>
READ

Confirm the failed state and exit code

2
journalctl -u <service> --since '10 min ago' --no-pager
READ

Read the failure reason from the journal

3
systemctl cat <service>
READ

Inspect the unit file configuration

4
systemctl restart <service>
CHANGE

Restart after fixing the root cause

Prevention

  • Test unit file changes with systemctl daemon-reload && systemctl start <service> before committing.
  • Use systemd-analyze verify <service> to check unit files for errors.
  • Set After= and Requires= dependencies so services start in the correct order.
  • Monitor service status via systemctl is-active and alert on failed state.

Related runbooks

Same stack, same failure family — worth a skim.

Address already in use — port binding conflicthigh

bind: Address already in use error on application startup

LinuxFoundation3 causes
Open runbook
Permission denied — file access denied due to ownership or modemedium

Permission denied when accessing a file or directory

LinuxFoundation3 causes
Open runbook
Systemd shutdown stuck — unit hangs during shutdown/rebootmedium

Shutdown or reboot hangs for minutes before eventually completing

LinuxAdvanced3 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.