docker/compose · error

container %s is unhealthy

Error message

container %s is unhealthy

What it means

Error "container %s is unhealthy" thrown in docker/compose.

Source

Thrown at pkg/compose/convergence.go:496

		if ctr.State.Status == container.StateExited {
			return false, fmt.Errorf("container %s exited (%d)", name, ctr.State.ExitCode)
		}

		noHealthcheck := ctr.Config.Healthcheck == nil || (len(ctr.Config.Healthcheck.Test) > 0 && ctr.Config.Healthcheck.Test[0] == "NONE")
		if noHealthcheck && fallbackRunning {
			// Container does not define a health check, but we can fall back to "running" state
			return ctr.State != nil && ctr.State.Status == container.StateRunning, nil
		}

		if ctr.State == nil || ctr.State.Health == nil {
			return false, fmt.Errorf("container %s has no healthcheck configured", name)
		}
		switch ctr.State.Health.Status {
		case container.Healthy:
			// Continue by checking the next container.
		case container.Unhealthy:
			return false, fmt.Errorf("container %s is unhealthy", name)
		case container.Starting:
			return false, nil
		default:
			return false, fmt.Errorf("container %s had unexpected health status %q", name, ctr.State.Health.Status)
		}
	}
	return true, nil
}

func (s *composeService) isServiceCompleted(ctx context.Context, containers Containers) (bool, int, error) {
	for _, c := range containers {
		res, err := s.apiClient().ContainerInspect(ctx, c.ID, client.ContainerInspectOptions{})
		if err != nil {
			return false, 0, err
		}
		if res.Container.State != nil && res.Container.State.Status == container.StateExited {
			return true, res.Container.State.ExitCode, nil
		}

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Run docker inspect on the unhealthy container to see the failing healthcheck output.
2. Fix the healthcheck command/interval/retries or the underlying application issue, then restart the stack.

When it happens

Trigger: A container's healthcheck reported status 'unhealthy' while compose was waiting for it to become healthy (e.g. via depends_on: service_healthy or --wait).

Common situations: The healthcheck command repeatedly fails (wrong port, missing binary, failing endpoint). Check 'docker inspect' Health log output for the failing probe.

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/a2b2ac1d1d6b98f3. Report an issue: GitHub.