docker/compose · error

dependency failed to start: %w

Error message

dependency failed to start: %w

What it means

Error "dependency failed to start: %w" thrown in docker/compose.

Source

Thrown at pkg/compose/convergence.go:218

						return err
					}
					if isHealthy {
						s.events.On(containerEvents(waitingFor, healthy)...)
						return nil
					}
				case types.ServiceConditionHealthy:
					isHealthy, err := s.isServiceHealthy(ctx, waitingFor, false)
					if err != nil {
						if !config.Required {
							s.events.On(containerReasonEvents(waitingFor, skippedEvent,
								fmt.Sprintf("optional dependency %q failed to start", dep))...)
							logrus.Warnf("optional dependency %q failed to start: %s", dep, err.Error())
							return nil
						}
						s.events.On(containerEvents(waitingFor, func(s string) api.Resource {
							return errorEventf(s, "dependency %s failed to start", dep)
						})...)
						return fmt.Errorf("dependency failed to start: %w", err)
					}
					if isHealthy {
						s.events.On(containerEvents(waitingFor, healthy)...)
						return nil
					}
				case types.ServiceConditionCompletedSuccessfully:
					isExited, code, err := s.isServiceCompleted(ctx, waitingFor)
					if err != nil {
						return err
					}
					if isExited {
						if code == 0 {
							s.events.On(containerEvents(waitingFor, exited)...)
							return nil
						}

						messageSuffix := fmt.Sprintf("%q didn't complete successfully: exit %d", dep, code)
						if !config.Required {

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Inspect the logs of the dependency container that failed to start (docker compose logs <service>) to find the root cause.
2. Fix the failing dependency's configuration, image, or start command, then run docker compose up again.
3. Check the dependency's depends_on conditions and healthchecks to ensure they can be satisfied.

When it happens

Trigger: Occurs during 'docker compose up' when a service listed in depends_on fails to start, causing the dependent service startup to abort. The wrapped error gives the underlying cause (container exit, healthcheck failure, or engine error).

Common situations: A dependency service crashes on boot, its healthcheck never passes, or the Docker engine rejects the container create/start request while another service waits on it.

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