docker/compose · error

container had unexpected health status

Error message

container %s had unexpected health status %q

What it means

Error "container %s had unexpected health status %q" thrown in docker/compose.

Solutions

1. Inspect the container with docker inspect to see the reported health status and healthcheck logs.
2. Ensure the image and Docker engine produce a recognized health status (healthy/unhealthy/starting); upgrade Docker if the status is unknown.

When it happens

Trigger: Docker reported a container health status other than healthy/unhealthy/starting while compose waited on it, which compose does not know how to handle.

Common situations: Rare engine or API inconsistency, or a container whose state was altered externally while compose monitored it.

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

Appendix: source

Thrown at pkg/compose/convergence.go:500

		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
		}
	}
	return false, 0, nil
}

View on GitHub (pinned to ddc4b044b6)