docker/compose · error

container %s had unexpected health status %q

Error message

container %s had unexpected health status %q

What it means

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

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)

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.