{"record":{"id":"a9bb85e3b8d34ff1","repo":"microsoft/aspire","slug":"resource-resource-name-stopped-waiting-for-dependency","errorCode":null,"errorMessage":"Resource '{resource.Name}' stopped waiting for dependency resource '{displayName}' because it failed to start.","messagePattern":"Resource '(.+?)' stopped waiting for dependency resource '(.+?)' because it failed to start\\.","errorType":"exception","errorClass":"DistributedApplicationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/ApplicationModel/ResourceNotificationService.cs","lineNumber":342,"sourceCode":"\n        async Task Core(string displayName, string resourceId)\n        {\n            var resourceEvent = await WaitForResourceCoreAsync(\n                dependency.Name,\n                re => re.ResourceId == resourceId && IsKnownTerminalState(re.Snapshot),\n                $\"Resource '{displayName}' failed to reach a terminal state before the operation was cancelled.\",\n                waitCondition: \"terminal\",\n                cancellationToken: cancellationToken).ConfigureAwait(false);\n            var snapshot = resourceEvent.Snapshot;\n\n            if (snapshot.State?.Text == KnownResourceStates.FailedToStart)\n            {\n                resourceLogger.LogError(\n                    \"Dependency resource '{ResourceName}' failed to start.\",\n                    displayName\n                    );\n\n                throw new DistributedApplicationException($\"Resource '{resource.Name}' stopped waiting for dependency resource '{displayName}' because it failed to start.\");\n            }\n            else if ((snapshot.State!.Text == KnownResourceStates.Finished || snapshot.State!.Text == KnownResourceStates.Exited) && snapshot.ExitCode is not null && snapshot.ExitCode != exitCode)\n            {\n                resourceLogger.LogError(\n                    \"Resource '{ResourceName}' has entered the '{State}' state with exit code '{ExitCode}' expected '{ExpectedExitCode}'.\",\n                    displayName,\n                    snapshot.State.Text,\n                    snapshot.ExitCode,\n                    exitCode\n                    );\n\n                throw new DistributedApplicationException(\n                    $\"Resource '{resource.Name}' stopped waiting for dependency resource '{displayName}' because it entered the '{snapshot.State.Text}' state with exit code '{snapshot.ExitCode}', expected '{exitCode}'.\"\n                    );\n            }\n\n            resourceLogger.LogInformation(\"Finished waiting for resource '{ResourceName}'.\", displayName);\n","sourceCodeStart":324,"sourceCodeEnd":360,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/ApplicationModel/ResourceNotificationService.cs#L324-L360","documentation":"Thrown by WaitUntilCompletionAsync when a dependency resource being waited on (via WaitForCompletion) reports FailedToStart. The waiting resource abandons the wait and fails with a message naming both the waiter and the dependency.","triggerScenarios":"builder.AddProject<X>(\"x\").WaitForCompletion(\"dependency\") (WaitType.WaitForCompletion) where the dependency snapshot's State.Text equals KnownResourceStates.FailedToStart.","commonSituations":"A migration/init container or console job fails before doing work (bad command, missing file, invalid image); dependency container image pull failure; dependency crashes during startup.","solutions":["Check the dependency resource's logs in the Aspire dashboard for the startup failure cause.","Fix the dependency's configuration (command, image, env vars) so it runs to completion.","If the dependency is long-running, use WaitForResourceHealthy/WaitUntilStarted rather than WaitForCompletion.","Retry transient causes (image pull/network) by restarting the AppHost after fixing registry access."],"exampleFix":"// before\nbuilder.AddProject<Projects.Worker>(\"worker\")\n    .WaitForCompletion(\"migrator\"); // migrator fails to start\n\n// after: verify the migrator command; e.g. fix args so it starts\nbuilder.AddProject<Projects.Migrator>(\"migrator\")\n    .WithArgs(\"run\", \"--correct-args\");\nbuilder.AddProject<Projects.Worker>(\"worker\")\n    .WaitForCompletion(\"migrator\");","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try\n{\n    await app.StartAsync();\n}\ncatch (DistributedApplicationException ex) when (ex.Message.Contains(\"failed to start\"))\n{\n    logger.LogError(ex, \"Dependency '{Dep}' failed to start before completion wait finished.\", depName);\n}","preventionTips":["Validate migration/init job commands and args locally before wiring WaitForCompletion.","Confirm container images exist and are pullable from configured registries.","Check dependency logs in the dashboard on any startup failure.","Order dependencies with WithReference so prerequisites exist before jobs run."],"tags":["aspire","dependency","wait-for-completion","startup"],"backgroundTag":"invalid-state-transition","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}