docker/compose · error

%s is missing dependency %s

Error message

%s is missing dependency %s

What it means

waitDependencies waits (500ms tick loop) for each dependency configured in depends_on until its containers are healthy/running. If the dependency service has zero non-one-off containers at wait time and the dependency is required (default, or `required: true`), waiting is pointless and this error is returned immediately; optional dependencies only log a warning instead.

Source

Thrown at pkg/compose/convergence.go:175

func (s *composeService) waitDependencies(ctx context.Context, project *types.Project, dependant string, dependencies types.DependsOnConfig, containers Containers, timeout time.Duration) error {
	if timeout > 0 {
		withTimeout, cancelFunc := context.WithTimeout(ctx, timeout)
		defer cancelFunc()
		ctx = withTimeout
	}
	eg, ctx := errgroup.WithContext(ctx)
	for dep, config := range dependencies {
		if shouldWait, err := shouldWaitForDependency(dep, config, project); err != nil {
			return err
		} else if !shouldWait {
			continue
		}

		waitingFor := containers.filter(isService(dep), isNotOneOff)
		s.events.On(containerEvents(waitingFor, waiting)...)
		if len(waitingFor) == 0 {
			if config.Required {
				return fmt.Errorf("%s is missing dependency %s", dependant, dep)
			}
			logrus.Warnf("%s is missing dependency %s", dependant, dep)
			continue
		}

		eg.Go(func() error {
			ticker := time.NewTicker(500 * time.Millisecond)
			defer ticker.Stop()
			for {
				select {
				case <-ticker.C:
				case <-ctx.Done():
					return nil
				}
				switch config.Condition {
				case ServiceConditionRunningOrHealthy:
					isHealthy, err := s.isServiceHealthy(ctx, waitingFor, true)
					if err != nil {

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Check why the dependency has no container: `docker compose ps -a`, `docker compose logs <dependency>` — usually the root cause is its own failed start
2. Fix the dependency name/typo or activate its profile (`--profile x`) so it is part of the project
3. If the dependency is genuinely optional, mark it `required: false` in depends_on to downgrade the failure to a warning

Example fix

# before
services:
  app:
    depends_on:
      db:
        condition: service_healthy  # db never created

# after (optional dependency)
services:
  app:
    depends_on:
      db:
        condition: service_healthy
        required: false

for dep, cfg := range svc.DependsOn {
    if !cfg.Required { continue }
    if len(containers.filter(isService(dep), isNotOneOff)) == 0 {
        return fmt.Errorf("required dependency %s of %s has no containers", dep, svc.Name)
    }
}

if err != nil && strings.Contains(err.Error(), "is missing dependency") {
    // inspect `docker compose ps -a <dep>`; fix provider startup or mark required:false, then re-up
}

When it happens

Trigger: `docker compose up` where service A declares `depends_on: {B: {condition: service_healthy, required: true}}` but B has no containers — B failed to create (bad image, failed build), or a prior error removed it before A's wait phase started.

Common situations: Dependency image pull/build failure whose error surfaced after dependent scheduling; depends_on referencing a service name behind a profile that wasn't activated; typos in the dependency key so it never maps to a real service; crash-looping dependencies recreated by `--force-recreate` races.

Related errors

• service %q didn't complete successfully: exit %d
• cannot share volume with service %s: container missing
• cannot share network namespace with service %s: container mi
• cannot share IPC namespace with service %s: container missin
• cannot share PID namespace with service %s: container missin

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