🚨 Linux Error: 'Unit <name>.service not found' — Cause, Fix, and Troubleshooting Guide

Summary

Unit <name>.service not found (often shown as Failed to start <name>.service: Unit <name>.service not found.) means systemd has no unit file registered under that exact name. It is not a runtime crash — systemd never found anything to run. The cause is nearly always a typo, a unit file in the wrong path, or a systemctl daemon-reload that never happened after the file was added.

Common Symptoms

• systemctl start foo returns Failed to start foo.service: Unit foo.service not found.
• systemctl status foo prints Unit foo.service could not be found.
• A freshly created unit works only after a daemon-reload.
• A dependency line references a unit that does not exist, so a different service fails at boot.
• systemctl enable foo fails with No such file or directory.

Most Likely Causes of the ‘Unit .service not found’ Error

The Unit <name>.service not found error means the name you passed does not resolve to any unit in the systemd load path. Common production causes, most frequent first:

1. A typo or wrong suffix — nginix, or asking for foo.service when the unit is foo.timer/foo.socket.
2. The unit file is in the wrong directory — dropped in /etc/systemd/ root or a home dir instead of /etc/systemd/system/.
3. daemon-reload was never run after creating or renaming the file, so systemd’s in-memory catalog is stale.
4. A dangling dependency — another unit lists Requires=/After= a service that was removed.
5. The package was uninstalled but a symlink under *.wants/ still points at the vanished unit.
6. Wrong scope — a --user unit invoked in system context (or vice versa).

Quick Triage

# Does systemd know the exact name? (fuzzy match)
systemctl list-unit-files | grep -i <name>
systemctl list-units --all | grep -i <name>

# Where does systemd look, and is the file there?
systemctl show --property=UnitPath
ls -l /etc/systemd/system /run/systemd/system /lib/systemd/system | grep <name>

Diagnostic Commands

systemctl status <name>.service           # confirms "could not be found"
systemctl cat <name>.service              # errors if no file is loaded
systemd-analyze verify /etc/systemd/system/<name>.service

systemctl cat is the fastest confirmation: if it errors, systemd genuinely has no loaded unit by that name. systemd-analyze verify on the file path checks the file even before it is loaded, catching bad [Unit]/[Service] directives.

# Find the actual file, wherever it landed
sudo find /etc/systemd /lib/systemd /run/systemd -iname '*<name>*'
systemctl list-dependencies --reverse <name>.service   # who references it
journalctl -u <name>.service -b                        # any load-time complaints

# For a dangling dependency causing another unit to fail
systemctl list-units --failed
grep -rEn 'Requires=|Wants=|After=|BindsTo=' /etc/systemd/system | grep <name>

Fix / Remediation

1. Confirm the exact name with systemctl list-unit-files | grep -i <name> and retry with the correct spelling and suffix.

2. Place the unit in the right directory and reload:

   sudo cp foo.service /etc/systemd/system/foo.service
   sudo systemctl daemon-reload
   systemctl cat foo.service               # now resolves

3. Enable it with a valid [Install] section. systemd cannot enable a unit that has no WantedBy=:

   [Install]
   WantedBy=multi-user.target

   sudo systemctl enable --now foo.service

4. Remove a dangling reference in the offending unit (Requires=/After=) or restore the missing dependency, then daemon-reload.

5. Clear a stale symlink left by an uninstalled package:

   sudo find /etc/systemd/system -xtype l -name '*<name>*'
   sudo rm /etc/systemd/system/multi-user.target.wants/<name>.service
   sudo systemctl daemon-reload

6. For user units, target the right scope:

   systemctl --user daemon-reload
   systemctl --user status <name>.service

Warning: Before deleting any *.wants/ symlink, confirm it is genuinely dangling with find -xtype l — removing a live link disables a working service.

Validation

systemctl cat <name>.service              # loads without error
systemctl status <name>.service           # shows loaded/active
systemctl is-enabled <name>.service
systemctl --failed                        # no lingering dependency failures

Prevention

• Always run sudo systemctl daemon-reload after adding, renaming, or editing a unit file.
• Keep custom units in /etc/systemd/system/ and use systemctl edit for drop-ins rather than editing vendor files.
• Give every enableable unit a correct [Install] WantedBy= so enable cannot fail.
• Run systemd-analyze verify /etc/systemd/system/<unit> in CI to catch bad references and missing dependencies before deploy.
• When removing a service, systemctl disable --now it first so no *.wants/ symlinks are orphaned. More at the Linux admins guides.

Related Errors

• Failed to start unit
• Start request repeated too quickly
• Dependency failed for /
• Failed to connect to bus: No such file or directory
• Permission denied

Final Notes

Unit <name>.service not found is a naming/registration problem, not a crash. Verify the exact unit name with systemctl list-unit-files, make sure the file lives in /etc/systemd/system/, and run daemon-reload. If the error appears while starting a different service, hunt down the dangling Requires=/After= reference and fix or remove it.

Want faster Linux incident response? Use DevOps AI Toolkit to turn production errors into clear diagnostics, remediation steps, and reusable runbooks.