Service won't start: how to fix it

Topic: Servers linux

Diagnose why a systemd unit fails to start: read journalctl -u UNIT, check config and paths, fix permissions and dependencies (sockets, mounts), then restart. Use this when systemctl start fails or the unit is in failed state.

Intent: Troubleshooting

Quick answer

  • systemctl status UNIT and journalctl -u UNIT -n 50 --no-pager show the error; common causes are config syntax, missing path, wrong user, or failed dependency.
  • Fix: correct config (e.g. nginx -t, php -t); create missing dirs and chown; ensure dependency units are active (sockets, mounts); then systemctl restart UNIT.
  • If unit is a template (name@.service), start with instance: systemctl start name@instance; check /etc/default or env for the service.

Prerequisites

Steps

  1. Read the failure

    systemctl status nginx; journalctl -u nginx -n 100 --no-pager; note the last line (e.g. failed to bind, permission denied, no such file).

  2. Check config and paths

    Run the daemon's config test (nginx -t, apachectl configtest); check WorkingDirectory, ExecStart path; ensure dirs exist and user can read/write.

  3. Check dependencies

    systemctl list-dependencies unit; ensure socket or mount units are active; start them or fix the unit so it does not require them if not needed.

  4. Fix and restart

    Edit config or create dirs; chown if needed; systemctl daemon-reload if you edited the unit; systemctl restart UNIT; verify status and journal again.

Summary

You will find why a systemd unit fails to start by reading status and logs, checking config and paths, and fixing dependencies or permissions. Use this whenever a service does not come up after install or config change.

Prerequisites

  • Root or sudo; the unit name (e.g. nginx, postgresql).

Steps

Step 1: Read the failure

systemctl status nginx
journalctl -u nginx -n 80 --no-pager

Look for “failed”, “error”, “cannot bind”, “permission denied”, “no such file”.

Step 2: Check config and paths

nginx -t
ls -la /var/lib/nginx
cat /etc/systemd/system/nginx.service.d/override.conf

Fix config syntax or create missing directories; set correct ownership.

Step 3: Check dependencies

systemctl list-dependencies nginx
systemctl status postgresql   # if nginx needs DB

Start required units or relax the unit so it can start without them (e.g. optional socket).

Step 4: Fix and restart

sudo systemctl daemon-reload
sudo systemctl restart nginx
systemctl status nginx
journalctl -u nginx -f

Verification

  • Unit is active (running); journal shows no new errors; the app responds (e.g. curl localhost).

Troubleshooting

Port already in use — Another process is bound to the port; ss -tlnp | grep :80; stop that process or change the service port.

Permission denied — Service runs as a specific user; ensure that user owns or can access the paths in ExecStart and WorkingDirectory.

Next steps

Continue to