docker/compose · error

timeout waiting for dependencies

Error message

timeout waiting for dependencies

What it means

Error "timeout waiting for dependencies" thrown in docker/compose.

Source

Thrown at pkg/compose/convergence.go:259

							return nil
						}

						msg := fmt.Sprintf("service %s", messageSuffix)
						s.events.On(containerEvents(waitingFor, func(s string) api.Resource {
							return errorEventf(s, "service %s", messageSuffix)
						})...)
						return errors.New(msg)
					}
				default:
					logrus.Warnf("unsupported depends_on condition: %s", config.Condition)
					return nil
				}
			}
		})
	}
	err := eg.Wait()
	if errors.Is(err, context.DeadlineExceeded) {
		return fmt.Errorf("timeout waiting for dependencies")
	}
	return err
}

func shouldWaitForDependency(serviceName string, dependencyConfig types.ServiceDependency, project *types.Project) (bool, error) {
	if dependencyConfig.Condition == types.ServiceConditionStarted {
		// already managed by InDependencyOrder
		return false, nil
	}
	if service, err := project.GetService(serviceName); err != nil {
		for _, ds := range project.DisabledServices {
			if ds.Name == serviceName {
				// don't wait for disabled service (--no-deps)
				return false, nil
			}
		}
		return false, err
	} else if service.GetScale() == 0 {

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Increase the wait timeout or investigate why the dependency is slow to become healthy.
2. Review the dependency's healthcheck configuration; an over-strict or broken healthcheck blocks startup.
3. Run docker compose ps and docker compose logs on the dependencies to see which one never became ready.

When it happens

Trigger: Raised when the dependencies of a service do not reach a healthy/started state before the wait deadline expires during service startup ordering.

Common situations: A dependency has a slow or failing healthcheck, a long-running initialization, or a condition such as service_healthy that never becomes true.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

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