Troubleshoot a Service
Use this page when a Service does not deploy, one component becomes degraded, the running configuration differs from the saved Compose definition, or clients cannot reach a component.
Start by identifying the failing layer. Do not restart the complete stack or change several settings before collecting evidence from the first failure.
Identify the failing layer
| Symptom | Start with |
|---|---|
| Deployment stops before the containers start | The first failed command in the deployment output. |
| One component is exited, restarting, or unhealthy | That component's status and container logs. |
| Containers run, but one component cannot reach another | The shared Docker network, internal hostname, and internal port. |
| The application works internally but its domain fails | The component domain, internal listening port, DNS, and Coolify Proxy. |
| The running container does not match the saved setting | Source Compose, Deployable Compose, and environment variables. |
Follow the matching symptom
Find the first failed deployment command
Open the deployment output for the failed Deploy, Restart, or image-pull operation. Start with the first command that reports an error; later failures can be consequences of that command.
Use the error to select the next check:
| Evidence | Check next |
|---|---|
| Image not found or registry authorization failed | Confirm the image name, tag, and registry credentials. |
| Compose validation or interpolation failed | Review Source Compose for invalid YAML, unsupported values, or an empty required variable. |
| Volume or bind-mount permission failed | Confirm the source exists on the Service server and that the container user can access it. |
| Container starts and immediately exits | Open Logs for that component and investigate the first application error. |
| Dependency is unavailable during startup | Confirm the dependency container is running, healthy, and reachable by its internal hostname and port. |
Apply only the correction supported by the error, then deploy again. Recovery is confirmed when the deployment completes and every required component remains running or healthy.
Collect information for support
If the Service still fails, record:
- the Service and affected component names
- the first failed deployment command and its error
- the affected component's status and relevant log lines
- the source and deployable Compose sections involved in the failure
- whether the problem affects internal traffic, a domain, or both
- the server and Docker networks shared by the relevant containers
- the remedies already attempted and their results
Remove passwords, tokens, private keys, and other secret values before sharing Compose or environment-variable output.