systemd Error: unit not found — causes and fixes

What does the "unit not found" error mean in systemd?

The error Failed to start <service_name>.service: Unit not found. (or simply Unit <name> not found.) occurs when the systemd daemon cannot find the configuration file (unit) with the name you specified in its directories. Systemd looks for service files (with the .service extension) in standard paths, such as /etc/systemd/system/ (administrator overrides) and /usr/lib/systemd/system/ (package files).

Typical full error text:

$ sudo systemctl start myapp.service
Failed to start myapp.service: Unit not found.

This error occurs when attempting to start, stop, restart, enable, or disable a service that systemd does not know.

Main causes of the error

1. Incorrect service name. You specified a name that does not match the file name (e.g., systemctl start nginx instead of systemctl start nginx.service, or with a typo).
2. The service file is missing from systemd directories. The .service file is not physically located in /etc/systemd/system/ or /usr/lib/systemd/system/.
3. The system has not reloaded configurations. You created or copied a service file but did not run systemctl daemon-reload. Systemd works with a static cache at startup.
4. Incorrect file location. The file is not in a directory that systemd scans (e.g., in /root/ or /home/user/).
5. Corrupted or invalid service file. The file exists but has syntax errors or missing required sections (though this more often causes other errors during loading).
6. Name conflict. There are multiple files with the same name in different directories, and systemd selects the wrong one (less common).

Ways to solve the "unit not found" error

Method 1: Check the exact name and find the unit

First, ensure you are using the correct name. Systemd can often automatically add .service, but it's better to specify it explicitly.

1. Search for existing services. Run the command to search by part of the name:

   systemctl list-unit-files --type=service --all | grep -i <part_of_service_name>
   

   
   The --all flag also shows disabled and inactive units. Example:

   systemctl list-unit-files --type=service --all | grep -i nginx
   

   
   Output:

   nginx.service                         enabled
   

   
   If nothing is output, the service with that name is not registered in systemd.
2. Try the full path. If you know where the file is located, specify its absolute path:

   sudo systemctl start /etc/systemd/system/myapp.service
   

Method 2: Reload the systemd daemon (daemon-reload)

This is the most common cause and solution after creating a new service file.

1. After creating or copying a .service file into /etc/systemd/system/, run:

   sudo systemctl daemon-reload
   

   
   This command forces systemd to re-read all configuration files from standard directories and update its internal unit manager.
2. After that, repeat the start/enable command:

   sudo systemctl start myapp.service
   # or
   sudo systemctl enable myapp.service
   

Method 3: Ensure the service file exists and has the correct name

1. Check for the file. Navigate to systemd directories and look for your file:

   ls -l /etc/systemd/system/*.service
   ls -l /usr/lib/systemd/system/*.service
   

   
   The file must exist in one of these directories (or their subdirectories). Typically, administrative services are placed in /etc/systemd/system/.
2. Check the file name. The file name must end with .service, and in the systemctl command you use this name without the path but with the extension (or without—systemd will add it).
   • Correct: sudo systemctl start myapp.service for the file myapp.service.
   • Incorrect: sudo systemctl start myapp (if there is no other unit with that name) or sudo systemctl start myapp. (with a dot).

Method 4: Create a correct service file

If the service does not actually exist, you need to create it.

1. Create the file in /etc/systemd/system/ (requires root privileges):

   sudo nano /etc/systemd/system/myapp.service
   

2. Add a minimal working configuration. Replace /usr/bin/myapp with the actual path to your application's executable file.

   [Unit]
   Description=My Custom Application
   After=network.target
   
   [Service]
   Type=simple
   ExecStart=/usr/bin/myapp --config /etc/myapp/config.conf
   Restart=on-failure
   RestartSec=5s
   
   [Install]
   WantedBy=multi-user.target
   

   • [Unit] — metadata and dependencies.
   • [Service] — how to run the process.
   • [Install] — how to enable (symbolic links for enable).
3. Save the file and perform Method 2 (daemon-reload), then Method 1 (check the name) and start it:

   sudo systemctl daemon-reload
   sudo systemctl start myapp.service
   sudo systemctl enable myapp.service  # for autostart
   

Method 5: Check syntax and file permissions

Sometimes systemd may "not see" a file due to permission or syntax issues.

1. Check syntax. Systemd can verify a config without loading it:

   sudo systemd-analyze verify /etc/systemd/system/myapp.service
   

   
   If the output is empty, the syntax is correct. On errors, it will indicate the line and problem.
2. Check permissions. The file must be readable by root:

   ls -l /etc/systemd/system/myapp.service
   

   
   Expected output: -rw-r--r-- 1 root root ... myapp.service. If permissions differ, fix them:

   sudo chmod 644 /etc/systemd/system/myapp.service
   sudo chown root:root /etc/systemd/system/myapp.service
   

Preventing the "unit not found" error

• Always run systemctl daemon-reload after any creation, deletion, or modification of service files in /etc/systemd/system/ or /usr/lib/systemd/system/.
• Use standard paths. Do not store .service files in random directories. Only /etc/systemd/system/ (for local settings) and /usr/lib/systemd/system/ (for packages).
• Follow naming conventions. The file name should be meaningful and end with .service. Avoid spaces and special characters in the name.
• Check the configuration before loading. Use systemd-analyze verify to check the syntax of a new file.
• Use systemctl status for diagnostics. If a service is "enabled" but does not start, the command sudo systemctl status myapp.service will show its current state and recent logs, helping to identify other issues (such as permission denied or failed to start).