{"record":{"id":"8626fbb7a4d9a938","repo":"docker/compose","slug":"dependency-failed-to-start-w","errorCode":null,"errorMessage":"dependency failed to start: %w","messagePattern":"dependency failed to start: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/convergence.go","lineNumber":218,"sourceCode":"\t\t\t\t\t\treturn err\n\t\t\t\t\t}\n\t\t\t\t\tif isHealthy {\n\t\t\t\t\t\ts.events.On(containerEvents(waitingFor, healthy)...)\n\t\t\t\t\t\treturn nil\n\t\t\t\t\t}\n\t\t\t\tcase types.ServiceConditionHealthy:\n\t\t\t\t\tisHealthy, err := s.isServiceHealthy(ctx, waitingFor, false)\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\tif !config.Required {\n\t\t\t\t\t\t\ts.events.On(containerReasonEvents(waitingFor, skippedEvent,\n\t\t\t\t\t\t\t\tfmt.Sprintf(\"optional dependency %q failed to start\", dep))...)\n\t\t\t\t\t\t\tlogrus.Warnf(\"optional dependency %q failed to start: %s\", dep, err.Error())\n\t\t\t\t\t\t\treturn nil\n\t\t\t\t\t\t}\n\t\t\t\t\t\ts.events.On(containerEvents(waitingFor, func(s string) api.Resource {\n\t\t\t\t\t\t\treturn errorEventf(s, \"dependency %s failed to start\", dep)\n\t\t\t\t\t\t})...)\n\t\t\t\t\t\treturn fmt.Errorf(\"dependency failed to start: %w\", err)\n\t\t\t\t\t}\n\t\t\t\t\tif isHealthy {\n\t\t\t\t\t\ts.events.On(containerEvents(waitingFor, healthy)...)\n\t\t\t\t\t\treturn nil\n\t\t\t\t\t}\n\t\t\t\tcase types.ServiceConditionCompletedSuccessfully:\n\t\t\t\t\tisExited, code, err := s.isServiceCompleted(ctx, waitingFor)\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\treturn err\n\t\t\t\t\t}\n\t\t\t\t\tif isExited {\n\t\t\t\t\t\tif code == 0 {\n\t\t\t\t\t\t\ts.events.On(containerEvents(waitingFor, exited)...)\n\t\t\t\t\t\t\treturn nil\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\tmessageSuffix := fmt.Sprintf(\"%q didn't complete successfully: exit %d\", dep, code)\n\t\t\t\t\t\tif !config.Required {","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/convergence.go#L200-L236","documentation":"Error \"dependency failed to start: %w\" thrown in docker/compose.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Inspect the logs of the dependency container that failed to start (docker compose logs <service>) to find the root cause.","Fix the failing dependency's configuration, image, or start command, then run docker compose up again.","Check the dependency's depends_on conditions and healthchecks to ensure they can be satisfied."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}