mediumAdvancedSymptom-first#systemd#shutdown#timeout#reboot#hung

Systemd shutdown stuck — unit hangs during shutdown/reboot

Shutdown or reboot hangs for minutes before eventually completing

Likely source:availabilitydeployment

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Shutdown or reboot hangs for minutes before eventually completing
  • systemctl list-jobs shows a blocked job during shutdown
  • A service takes the full DefaultTimeoutStopSec before being killed

A slow shutdown is usually a slow service, not a systemd bug. Find the specific service blocking the sequence and fix its shutdown behavior.

Evidence to grab

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

  • Pending systemd jobs

    systemctl list-jobs

  • Journal shutdown messages

    journalctl -b -1 -p err --no-pager | tail -30

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 systemd waiting for the full TimeoutStopSec
  • The service does not respond to SIGTERM

Confirm before fixing

systemctl show <service> | grep -E 'TimeoutStopSec|ExecStop'
READ

Check the stop timeout and ExecStop command

Fix

systemctl edit <service> --force
CHANGE

Override TimeoutStopSec to a shorter value and add a proper ExecStop

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 list-jobs
READ

Find the job blocking shutdown

2
journalctl -b -1 --no-pager | grep -i 'stop\|timeout' | tail -20
READ

Read shutdown logs to find the slow service

3
systemctl edit <service> --force
CHANGE

Override the slow service's TimeoutStopSec

4
shutdown -r now
DESTRUCTIVE

Reboot again after fixing the timeout

Prevention

  • Set TimeoutStopSec= in every service unit file to a reasonable value (15-30s).
  • Test service shutdown behavior with systemctl stop <service> during maintenance.
  • Use soft NFS mount options (soft,timeo=30) to prevent mount hangs during shutdown.
  • Use systemd-analyze plot to visualize the shutdown dependency chain.

Related runbooks

Same stack, same failure family — worth a skim.

Systemd service fails to start — unit enters failed statehigh

systemctl status <service> shows failed state

LinuxFoundation3 causes
Open runbook
NFS mount hang — processes stuck in D-state on NFScritical

Processes stuck in D (uninterruptible sleep) state

LinuxAdvancedUSE3 causes
Open runbook

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