Docker Compose Service Unhealthy Fix

An unhealthy container is running but failing its healthcheck. Debug the healthcheck command and the service logs together.

Symptoms

  • docker compose ps shows unhealthy.
  • Dependent services wait or fail.
  • The app starts slowly and healthcheck fails early.

Likely causes

  • Healthcheck command uses the wrong host, port or path.
  • Service is still starting when checks begin.
  • Missing env variables or database dependencies break the app.

Fix steps

  1. Inspect docker compose logs for the service.
  2. Run the healthcheck command inside the container.
  3. Increase start_period for slow boot services.
  4. Verify required env variables and dependent services.

Verify the fix

  • Run docker inspect and review health logs.
  • Confirm the service endpoint responds inside the network.
  • Restart with a clean, known env file.

FAQ

Does unhealthy mean the container crashed?

No. It can be running while its healthcheck fails.

Should I remove healthchecks?

Only temporarily for debugging. A useful healthcheck catches real startup failures.

Related tools and guides

Docker Docker Compose Generator

Generate starter docker-compose.yml snippets for common local development stacks.

 ENV .env Generator

Generate clean .env starter files for local development, app configuration, databases, Redis, mail and API placeholders.

 HTTP HTTP Status Code Explainer

Explain common HTTP status codes with likely causes, API debugging notes and practical verification commands.

 Docker Docker Compose and .env Workflow for Local Development

Local stacks are easier to maintain when docker-compose.yml describes services and .env.example documents configuration without real secrets.

Last updated: May 18, 2026