Linux troubleshooting guide
Linux service not starting: a systemd investigation
A stopped service, a failed startup and an application that is running but unreachable are different situations. Establish which symptom is present before restarting or changing configuration.
Before you begin: These examples apply to Linux hosts using systemd. The unit name, permissions and application-specific checks depend on the actual service and distribution. These examples are not executed or verified against your system. Obtain authorization, protect sensitive output and involve the responsible owner.
Clarify the incident
Collect the relevant scope and timeline before choosing an action:
- Which service, host and version are affected, and when did the failure begin?
- Did a deployment, configuration change or dependency failure occur at the same time?
- Does the service fail locally, through its health check, or only from particular clients?
Possible explanations
These are alternatives to investigate, not confirmed causes:
- A process may have exited or failed to start; service state and the first relevant error can help distinguish these cases.
- A dependency, configuration, resource limit or network path may be involved; none is established by the demonstration.
Read-only checks
Replace example names and paths only after confirming the applicable platform, permissions and change policy. Command output can contain sensitive data.
Linux with systemd: service state
Replace the example unit with the correct service. If it is inactive, inspect its earlier events; if active but clients fail, compare its health check and network path. Output may be sensitive.
systemctl status your-service.service --no-pagerLinux with systemd: recent service logs
Compare the first relevant error and timestamp with dependencies and recent changes. Absence of an error in the last 50 lines does not rule out an earlier failure; redact output before sharing.
journalctl -u your-service.service -n 50 --no-pagerInterpret the evidence
Inactive or failed unit
Compare the unit state and the first relevant error with the event time. An inactive unit may also have been intentionally stopped; confirm the expected state with its owner.
Active unit but failing clients
A running process does not prove the application is healthy or reachable. Compare the application health check, dependencies, listening endpoint and authorized network path.
A recent change or dependency error
Correlate the failure with the actual deployment, configuration and dependency history. Validate a candidate using the application vendor procedure before activation.
Plan recovery and verification
- Confirm scope and safety: Identify affected services and users, contact the owner, and follow the incident and change process.
- Gather evidence: Check the applicable service manager, recent logs, dependencies, health checks and recent changes for the actual host and version.
- Prepare rollback: Keep a recovery route and the previous approved configuration available before making changes.
- Choose a controlled action: Agree on a remediation with the owner. A restart may temporarily restore service but can hide the underlying cause.
- Verify and monitor: Check application health and user impact after the approved action, then monitor for recurrence.
Watch for recurrence: After an approved recovery, monitor the service, dependency health and user-facing checks. If it fails again, preserve the new event time and compare it with the original evidence rather than repeatedly restarting it.
Documentation pointers
Check the documentation for your product and installed version. These links are references, not live verification.
Explore a safe demonstration
The scenario lab illustrates a fixed example. It does not reproduce this incident or verify a production fix, and it never executes your commands.
Open the related scenario lab