🚨 Linux Error Guide: 'Failed to start foo.service: Unit foo.service not found.' — Reload and fix the unit path

Overview

You try to start a service and systemd flatly refuses, telling you it has never heard of the unit you just wrote:

Failed to start foo.service: Unit foo.service not found.

This message means the systemd manager could not locate a loadable unit named foo.service anywhere in its unit search path, or the unit exists but is in a state (such as masked) that prevents it from being resolved. It is almost never a bug in systemd itself. In practice it is one of a small handful of causes: the unit file is not where systemd looks, systemd’s in-memory view of units is stale, the name has a typo, you dropped the .service suffix, or you are trying to start a template unit without an instance name.

The good news is that this class of failure is fully diagnosable with read-only commands before you change anything. This guide walks through the symptoms, the common root causes, and a repeatable diagnostic workflow so you can go from “not found” to a running service quickly and without guesswork.

Symptoms

• systemctl start foo (or systemctl restart foo, enable, status) returns Unit foo.service not found.
• systemctl status foo shows Loaded: not-found (Reason: Unit foo.service not found.) or, on older releases, Loaded: not-found (Reason: No such file or directory).
• Tab-completion of the unit name in the shell does not offer foo.
• The service worked before a rename, a package reinstall, or a move of the unit file, and now cannot be started.
• A freshly created /etc/systemd/system/foo.service still reports not-found until systemd is told to reload.

Common Root Causes

1. Unit file not installed or in the wrong path. systemd only reads units from its search path. For system units that is primarily /etc/systemd/system (administrator overrides), /run/systemd/system (runtime), and /usr/lib/systemd/system (packages, sometimes /lib/systemd/system). A unit dropped in your home directory or /opt will not be seen.

2. systemd has not reloaded. systemd caches the unit catalog in memory. After you add or edit a unit file on disk, the manager will not notice it until you run systemctl daemon-reload.

3. Typo in the unit name. foo.serivce, Foo.service, or a trailing space produces a name that does not match the file. Unit names are case-sensitive.

4. Missing .service suffix confusion. systemctl start foo is normally fine because systemctl assumes .service, but if your file is actually foo.target or foo.timer, the implicit .service lookup fails.

5. User vs system scope. A unit installed under ~/.config/systemd/user/ is a user unit and is invisible to the system manager. You must use systemctl --user start foo, and vice versa.

6. Template unit needs an instance. A file named foo@.service is a template. You cannot start foo@ directly. You start an instance such as foo@bar.service, where bar is passed to the unit as %i.

7. Masked unit. A masked unit is symlinked to /dev/null and deliberately unstartable. Masking can also surface as a not-found-adjacent refusal depending on the systemd version.

Diagnostic Workflow

Start with the unit’s own view of itself. status and cat tell you whether systemd can see the file at all and where it thinks the file lives.

systemctl status foo
systemctl cat foo

If cat prints the unit contents, the file is found and the problem is elsewhere (likely masking or an instance name). If it errors with “No files found for foo.service”, systemd genuinely cannot locate it.

List every unit file systemd currently knows about and filter for your name. This is the authoritative catalog:

systemctl list-unit-files | grep foo

If the file is on disk but not in that list, systemd has not reloaded its catalog. Force a reload and try again:

sudo systemctl daemon-reload
systemctl list-unit-files | grep foo

Confirm the file actually exists in a directory systemd reads, and check its exact name and suffix:

ls -l /etc/systemd/system/
ls -l /usr/lib/systemd/system/ | grep foo

Validate the unit’s syntax and references without starting it. systemd-analyze verify parses the file the same way the manager does and reports typos in directives or bad dependencies:

systemd-analyze verify /etc/systemd/system/foo.service

Check whether the unit is masked or in an unusual enable state:

systemctl is-enabled foo
systemctl is-active foo

If is-enabled returns masked, unmask it:

sudo systemctl unmask foo
sudo systemctl daemon-reload

Finally, if the unit did load but later failed, its logs live in the journal:

journalctl -u foo -b --no-pager

For a user-scoped unit, mirror the same commands with the --user flag:

systemctl --user daemon-reload
systemctl --user status foo

Example Root Cause Analysis

An engineer wrote a small worker service. They created the file, ran sudo systemctl start dataworker, and got Failed to start dataworker.service: Unit dataworker.service not found.

First check:

systemctl cat dataworker
# No files found for dataworker.service.

So systemd cannot see it. They confirm the file exists:

ls -l /etc/systemd/system/ | grep dataworker
# -rw-r--r-- 1 root root 412 Jul  7 09:14 dataworker.service

The file is present in the correct directory, which points squarely at a stale catalog. They reload and retry:

sudo systemctl daemon-reload
systemctl list-unit-files | grep dataworker
# dataworker.service   disabled   enabled

Now the unit appears. systemctl start dataworker succeeds. The root cause was simply that the unit was created after systemd had built its in-memory catalog, and no daemon-reload had been issued. Had the file instead lived in /opt/dataworker/dataworker.service, no reload would have helped, because that path is outside the search path; the fix there is to move or symlink the file into /etc/systemd/system/.

Prevention Best Practices

• Always daemon-reload after touching unit files. Make it a reflex: edit the file, then sudo systemctl daemon-reload, then start.
• Prefer systemctl edit for overrides. systemctl edit foo creates drop-ins in the right directory and reloads for you, removing path mistakes entirely.
• Validate before deploying. Run systemd-analyze verify /path/to/unit.service in CI or before enabling a unit, so typos in directive names are caught early.
• Be explicit about scope. Decide up front whether a workload is a system unit or a user unit, and document which systemctl invocation operators should use.
• Name template instances clearly. If you use foo@.service, document the expected instance names and enable them explicitly, e.g. systemctl enable foo@production.service.
• Avoid masking as a quick fix. If you mask a unit to silence it, record it, because a masked unit can baffle the next person who tries to start it.

Quick Command Reference

# See what systemd thinks of the unit
systemctl status foo
systemctl cat foo
systemctl is-enabled foo

# Is the unit in systemd's catalog?
systemctl list-unit-files | grep foo

# Pick up new or edited unit files
sudo systemctl daemon-reload

# Confirm the file exists in a search path
ls -l /etc/systemd/system/
ls -l /usr/lib/systemd/system/ | grep foo

# Validate syntax without starting
systemd-analyze verify /etc/systemd/system/foo.service

# Unmask a deliberately disabled unit
sudo systemctl unmask foo

# Start a template instance, not the template
sudo systemctl start foo@bar.service

# User-scoped units
systemctl --user daemon-reload
systemctl --user status foo

# Read the logs
journalctl -u foo -b --no-pager

Conclusion

Unit foo.service not found. is systemd telling you it cannot resolve the name you gave it to a loadable file in its search path. Work the problem in order: ask systemd what it sees with systemctl cat and list-unit-files, reload the catalog with daemon-reload, confirm the file is in /etc/systemd/system or /usr/lib/systemd/system, verify the exact name and suffix, and check for masking or a template that needs an instance. Because every step is a read-only inspection until the final fix, you can diagnose this confidently without risking further breakage, and the same workflow applies whether the unit is system-scoped or user-scoped.