docker/compose · error

container %s has no healthcheck configured

Error message

container %s has no healthcheck configured

What it means

Error "container %s has no healthcheck configured" thrown in docker/compose.

Source

Thrown at pkg/compose/convergence.go:490

		res, err := s.apiClient().ContainerInspect(ctx, c.ID, client.ContainerInspectOptions{})
		if err != nil {
			return false, err
		}
		ctr := res.Container
		name := ctr.Name[1:]

		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{})

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Add a healthcheck section to the service in the compose file, or drop the depends_on condition: service_healthy requirement.
2. Use condition: service_started instead of service_healthy if no healthcheck is needed.

When it happens

Trigger: Raised when a dependency condition requires 'service_healthy' but the target container defines no healthcheck, so compose can never observe a healthy state.

Common situations: The compose file uses depends_on with condition: service_healthy on a service whose definition (or image) lacks a HEALTHCHECK instruction.

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