Search guides

Fix a systemd service that fails

We'll check systemctl status, journalctl -xe, ExecStart path, unit file, and permissions—or tell you when to escalate.

Troubleshooting · Servers & Linux
15–30 min
What you'll need
  • SSH or console access with sudo
Step 1 of 5

Quick triage — pick your path

Quick triage — pick your path

Choose the option that matches what you see. You can jump straight to that section.

Show full guide

Steps

Goal: Confirm the service fails, read the error from journalctl, then fix ExecStart, permissions, or port—or escalate.

  • Run systemctl status servicename to see the current state.
  • Good: You see failed, inactive, or activating. Proceed to Check status and logs.
  • Bad: Service not found—check the exact unit name with systemctl list-units.

Check status and logs

Goal: See why the service failed.

  • Run systemctl status servicename. Note the Active line and the error.
  • Run journalctl -xe for recent system logs, or journalctl -u servicename -n 50 for service-specific logs. Look for Permission denied, failed to execute, no such file, or address already in use.
  • Good: You see the error. Proceed to Check ExecStart and unit file.
  • Bad: Logs unclear—run systemctl cat servicename to inspect the unit.

Check ExecStart and unit file

Goal: Confirm the ExecStart path and unit config are valid.

  • Run systemctl cat servicename to see the effective unit. Check ExecStart=—the path must exist. Run which binary or ls -la /path/to/binary to confirm.
  • Check User= and Group= if the service runs as non-root. Check WorkingDirectory= if it needs a specific cwd.
  • Good: Path exists and config looks correct. Proceed to Fix permissions or ports if the error points there.
  • Bad: ExecStart path wrong or missing—use sudo systemctl edit servicename to override, then daemon-reload and restart.

Fix permissions or ports

Goal: Fix permission denied or port conflicts.

  • If “Permission denied”: run ls -la on config files and data dirs. Use chown or chmod so the service user can access them.
  • If “address already in use”: run ss -tlnp or lsof -i :port to find the conflicting process. Stop it or change the port in your config.
  • Run sudo systemctl daemon-reload and sudo systemctl restart servicename.
  • Good: Service starts and systemctl status shows active (running).
  • Bad: Still fails—test the executable manually or escalate.

When to escalate

Escalate if:

  • The service is managed by Puppet, Ansible, or Chef.
  • The fix requires application code changes.
  • You cannot safely modify the unit file.

Provide systemctl status, journalctl -u servicename output, and systemctl cat servicename.

Verification

  • systemctl status servicename shows active (running).
  • No errors in journalctl -u servicename -n 20.
  • The service responds as expected (e.g. port listening, process running).

Escalation ladder

Work from the device outward. Stop when the problem is fixed.

  1. Status and logs systemctl status; journalctl -xe or journalctl -u servicename.
  2. Unit file and ExecStart systemctl cat; fix ExecStart path, User, WorkingDirectory.
  3. Permissions and ports chown/chmod; check port conflicts with ss/lsof.
  4. Escalate Provide status, journalctl, unit file.

What to capture if you need help

Before calling support or posting for help, have these ready. It speeds everything up.

  • systemctl status output
  • journalctl -u servicename output (or journalctl -xe)
  • Unit file (systemctl cat)
  • Steps already tried

What does journalctl show for the service?

Read the last 50 lines of service logs or journalctl -xe.

Run `journalctl -u servicename -n 50` or `journalctl -xe`. Permission denied: fix chown/chmod. No such file / failed to execute: fix ExecStart path. Address in use: check port with ss -tlnp. Other: check unit file and dependencies.

Yes Unclear

You can change your answer later.

Check status and ExecStart

Run `systemctl status servicename`. Note the Active line and error. Run `systemctl cat servicename` to see the unit. Check ExecStart path exists. Fix ExecStart, User, WorkingDirectory. daemon-reload, restart.

Done

Apply fix

Permission: chown/chmod for service user. Path: fix ExecStart in unit with systemctl edit. Port: stop conflicting service or change port. Dependencies: start required units. systemctl daemon-reload; systemctl restart servicename.

Yes No

You can change your answer later.

Test executable manually

Run the binary manually as the service user: sudo -u serviceuser /path/to/binary. See the error. Fix config or environment. If still unclear, escalate with systemctl status, journalctl, and unit file.

Done

Service is running

systemctl status shows active (running). No further action needed.

Done

Reviewed by Blackbox Atlas

Frequently asked questions

Why would a systemd service fail to start?
Wrong ExecStart path, permission denied, port already in use, missing dependency, or config error in the unit file. Check systemctl status and journalctl first.
Can I fix a failing systemd service myself?
Yes. Read journalctl for the error, fix ExecStart path or permissions, check port conflicts. Use systemctl edit servicename for overrides, then systemctl daemon-reload and restart.
When should I escalate service failures?
If the service is managed by config management, the fix requires application-level changes, or you cannot safely modify the unit file.

Rate this guide

Was this helpful?

Continue to