Safe Deployments
Docker Healthcheck Debugging Guide
Debug Docker healthcheck failures by reproducing the probe inside the image and separating command, timing, dependency and application-readiness problems. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.
Recommended workflow
| Step | Why it matters |
|---|---|
| Read probe history | Inspect exit codes and output for each recent healthcheck attempt. |
| Run the exact command | Execute the probe inside the same image with the same user, path and environment. |
| Review timing | Compare interval, timeout, retries and start period with realistic application startup. |
| Separate dependencies | Make the probe represent this container's readiness rather than every remote service. |
Starter snippet
docker inspect --format '{{json .State.Health}}' <container>Review checks
- Keep probe output short and non-sensitive.
- Use tools that actually exist in the runtime image.
- Test failure and recovery transitions.
- Distinguish liveness from readiness at the orchestrator layer.
Common mistakes
- Installing curl only for an oversized probe.
- Checking a public endpoint that bypasses the container.
- Using an aggressive timeout during cold startup.
Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.
Related Formalint references
Continue with Docker Container Logs Guide, Application Health Check Guide, Docker Compose Debugging Guide.