P2
Service Failed to Start — Systemd Troubleshooting Guide
Diagnose and fix a systemd service that fails to start or keeps crashing. Covers unit file inspection, dependency resolution, port conflicts, and manual testing.
15 min7 steps
Progress: 0/7 steps
0%
Get the current state of the service and recent logs.
systemctl status SERVICE_NAME -l --no-pager
Expected: Shows active/inactive/failed state, PID, memory, and recent log lines. Look for 'Active: failed' and the error message.
Get detailed logs from the journal for this service.
journalctl -u SERVICE_NAME --since '1 hour ago' --no-pager | tail -50
Expected: Full log output. Look for error messages, permission denied, missing files, or port conflicts.
Review the service configuration for errors.
systemctl cat SERVICE_NAME
Expected: The full unit file contents. Check ExecStart path, User, WorkingDirectory, and Environment settings.
Confirm the binary or script referenced in ExecStart exists and is executable.
# Extract ExecStart path from unit file and check it:
EXEC=$(systemctl show SERVICE_NAME -p ExecStart --value | awk '{print $1}' | sed 's/.*path=//;s/;.*//') && ls -la $EXECExpected: File should exist and have execute permissions.
If the service listens on a port, ensure nothing else is using it.
ss -tlnp | grep :PORT_NUMBER
Expected: If another process is already using the port, you'll see it here. Kill it or change the port.
Try running the service binary manually to see detailed error output.
# Run the ExecStart command manually: sudo -u SERVICE_USER /path/to/binary --config /path/to/config
Expected: Direct error output without systemd buffering. Often reveals missing dependencies or config errors.
Run as the same user specified in the unit file (User= directive), not as root (unless the service runs as root).
After fixing the issue, reload and restart.
systemctl daemon-reload && systemctl restart SERVICE_NAME && systemctl status SERVICE_NAME
Expected: Service should now show 'Active: active (running)'.