Home / Alt manpages / systemd-boot-check-no-failures.service(8)

  • systemd-boot-check-no-failures.service(8)
  • Admin command
  • linux

Use systemd-boot-check-no-failures to Gate Boot Completion

Boot never seems to fully finish, and systemd-boot-check-no-failures.service is the tiny gate meant to catch exactly that. This guide covers inspecting the service safely, running its underlying check by hand, and deciding whether its very small test suits your boot policy. Examples use systemd 255.4-1ubuntu8.17, installed here on Ubuntu. Allow about fifteen minutes.

The route

Jump straight to the step you need, or tick off Done means at the end.

  • Reading status is normally unprivileged.
  • Enabling or starting the service changes boot behaviour and needs root, so that step is kept separate below.

1. Check whether the service is in use

Start with read-only status queries. None of these enable, start, stop or reset anything:

$ systemctl is-enabled systemd-boot-check-no-failures.service
disabled
$ systemctl is-active systemd-boot-check-no-failures.service
inactive
$ systemctl cat systemd-boot-check-no-failures.service

The installed unit is a oneshot service. It runs /usr/lib/systemd/systemd-boot-check-no-failures, stays marked active after a successful run, and is installed as a requirement of boot-complete.target. It is disabled by default, so an inactive result on its own is not an error.

Checkpoint

Confirm you are inspecting the expected unit and that its ExecStart path exists.

$ test -x /usr/lib/systemd/systemd-boot-check-no-failures && echo executable
executable

2. Run the helper without changing the system

The helper is the smallest reproducible part of the check. Run it directly as an ordinary command:

$ /usr/lib/systemd/systemd-boot-check-no-failures
Health check: 0 units have failed.

A message reporting zero failed units and exit status 0 is the healthy result. That number is not a general boot-quality score; this helper only checks whether systemd currently has failed units.

Capture the status explicitly when using it in a shell or diagnostic script:

$ /usr/lib/systemd/systemd-boot-check-no-failures
$ rc=$?
$ printf 'exit status: %s\n' "$rc"
exit status: 0

A non-zero count means a non-zero exit. On this host the command printed Health check: 1 units have failed. and returned status 1 because certbot.service was failed. That is a genuine failed-unit result, not a request to restart the service automatically.

3. Identify what failed before changing anything

Use systemctl to list failed units, then inspect the named unit. These commands are read-only:

$ systemctl --failed --no-legend --no-pager
certbot.service loaded failed failed Certbot
$ systemctl status certbot.service --no-pager
$ journalctl -u certbot.service -b --no-pager

Your output will differ; treat the unit name and its logs as the starting point for diagnosis.

Warning

Do not clear a failure with systemctl reset-failed merely to make the boot check pass. That changes the manager's recorded state and hides the symptom without fixing its cause.

Checkpoint

Rerun the helper only after you understand the failed unit. A zero result means no units are currently recorded as failed; it does not prove a service is correctly configured, reachable or ready for your application.

4. Understand what enabling it changes

The manual describes this service as an example for developing more fine-grained checks. When enabled, it is ordered before boot-complete.target, so its purpose is to prevent that target being reached when the simple failed-unit test reports a problem.

Enabling the service is a persistent, boot-affecting change and requires elevated privileges:

$ sudo systemctl enable systemd-boot-check-no-failures.service
Created symlink .../boot-complete.target.requires/systemd-boot-check-no-failures.service ...

The symlink path and exact message vary by distribution. Check the result without starting a boot transaction:

$ systemctl is-enabled systemd-boot-check-no-failures.service
enabled
$ systemctl cat systemd-boot-check-no-failures.service

There is no need to start the service manually just to test the helper. If you enabled it by mistake, undo that persistent change with:

$ sudo systemctl disable systemd-boot-check-no-failures.service

Disabling it removes the enablement relationship. It does not repair any failed unit and does not undo a service run that already happened.

Common traps

  • Treating this as a complete boot health policy. A failed-unit count is deliberately broad and shallow. A unit can be active while its application is unusable, and a unit can be failed for a reason that is harmless on a particular machine. It does not test network reachability, storage contents, application readiness, data integrity or a specific security property.
  • Blocking boot without an escape hatch. A check that blocks boot completion can affect recovery and automation, so keep console or out-of-band access available before enabling one, and test the failure path first in a maintenance window.
  • Copying the manpage's path literally. The local systemd 255 manpage has a small packaging mismatch: its synopsis shows /usr/lib/systemd/system-boot-check-no-failures, while this host's installed unit starts /usr/lib/systemd/systemd-boot-check-no-failures. Follow the unit's ExecStart and verify the executable on the host rather than copying the synopsis blindly.

Done means

  • You checked whether the service is enabled before changing it.
  • You ran the installed helper and checked both its message and exit status.
  • You inspected failed units and their logs instead of hiding failures with reset-failed.
  • You know enabling the service changes the relationship with boot-complete.target.
  • You can undo an accidental enablement with systemctl disable.
  • You have not treated this minimal count as a complete application health check.