adminLinux Service Dependency Troubleshooting Checklist
A Linux service often depends on other services, files, ports, users, environment variables or mounted disks. When a service fails, the real cause may be a missing dependency rather than the service binary itself.
Core principle
A service starts successfully only when its dependencies are available. Troubleshooting should ask: what does this service need before it can run?
Checklist
- Identify the failed service.
- Check service status.
- Read recent journal logs.
- List service dependencies.
- Check required files and directories.
- Check required users and permissions.
- Check required ports.
- Check required network or mount availability.
- Check environment variables or config files.
- Restart after fixing the confirmed dependency.
Reusable lesson
This applies to Nginx, PHP-FPM, MySQL, Docker, n8n, custom workers, API services and monitoring agents.
When to Use This Checklist
Use this checklist when a Linux service fails to start, starts only manually or breaks after reboot or configuration changes.
Required Tools
SSH access, systemctl, journalctl, service unit, config files, ss, ls, user and permission checks
Before You Start
Check logs before editing service files. A dependency error is usually visible in journal output or service status.
Structured Checklist Steps
- Identify failed service.
- Check status.
- Read logs.
- List dependencies.
- Check required files.
- Check required user.
- Check ports.
- Check network and mounts.
- Check environment.
- Restart after confirmed fix.
Verification Steps
- Failed dependency is identified.
- Required files exist.
- Required user and permission are correct.
- Port conflict is ruled out.
- Service starts cleanly.
Rollback Plan
If a dependency fix breaks another service, restore the previous config and resolve the dependency with a narrower change.
Common Mistakes
- Restarting repeatedly without logs.
- Ignoring missing directories.
- Forgetting service user permissions.
- Missing environment variables.
- Not checking port conflicts.
Related Commands
systemctl status service_name
journalctl -u service_name --since "30 minutes ago"
systemctl list-dependencies service_name
systemctl cat service_name
sudo ss -tulpn
ls -la /path/to/app
sudo systemctl restart service_name