microsoft/aspire · error · DistributedApplicationException

Resource ' ' stopped waiting for dependency resource ' '…

Error message

Resource '{resource.Name}' stopped waiting for dependency resource '{displayName}' because it failed to start.

What it means

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.

Solutions

1. Check the dependency resource's logs in the Aspire dashboard for the startup failure cause.
2. Fix the dependency's configuration (command, image, env vars) so it runs to completion.
3. If the dependency is long-running, use WaitForResourceHealthy/WaitUntilStarted rather than WaitForCompletion.
4. Retry transient causes (image pull/network) by restarting the AppHost after fixing registry access.

Example fix

// before
builder.AddProject<Projects.Worker>("worker")
    .WaitForCompletion("migrator"); // migrator fails to start

// after: verify the migrator command; e.g. fix args so it starts
builder.AddProject<Projects.Migrator>("migrator")
    .WithArgs("run", "--correct-args");
builder.AddProject<Projects.Worker>("worker")
    .WaitForCompletion("migrator");

try
{
    await app.StartAsync();
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("failed to start"))
{
    logger.LogError(ex, "Dependency '{Dep}' failed to start before completion wait finished.", depName);
}

When it happens

Trigger: builder.AddProject<X>("x").WaitForCompletion("dependency") (WaitType.WaitForCompletion) where the dependency snapshot's State.Text equals KnownResourceStates.FailedToStart.

Common situations: 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.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Resource ' ' stopped waiting for dependency resource ' '…
• Failed to send request
• Resource ' ' stopped waiting for dependency resource ' '…
• Stopped waiting for resource
• A circular lifetime reference was detected for resource

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/a9bb85e3b8d34ff1. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting/ApplicationModel/ResourceNotificationService.cs:342

        async Task Core(string displayName, string resourceId)
        {
            var resourceEvent = await WaitForResourceCoreAsync(
                dependency.Name,
                re => re.ResourceId == resourceId && IsKnownTerminalState(re.Snapshot),
                $"Resource '{displayName}' failed to reach a terminal state before the operation was cancelled.",
                waitCondition: "terminal",
                cancellationToken: cancellationToken).ConfigureAwait(false);
            var snapshot = resourceEvent.Snapshot;

            if (snapshot.State?.Text == KnownResourceStates.FailedToStart)
            {
                resourceLogger.LogError(
                    "Dependency resource '{ResourceName}' failed to start.",
                    displayName
                    );

                throw new DistributedApplicationException($"Resource '{resource.Name}' stopped waiting for dependency resource '{displayName}' because it failed to start.");
            }
            else if ((snapshot.State!.Text == KnownResourceStates.Finished || snapshot.State!.Text == KnownResourceStates.Exited) && snapshot.ExitCode is not null && snapshot.ExitCode != exitCode)
            {
                resourceLogger.LogError(
                    "Resource '{ResourceName}' has entered the '{State}' state with exit code '{ExitCode}' expected '{ExpectedExitCode}'.",
                    displayName,
                    snapshot.State.Text,
                    snapshot.ExitCode,
                    exitCode
                    );

                throw new DistributedApplicationException(
                    $"Resource '{resource.Name}' stopped waiting for dependency resource '{displayName}' because it entered the '{snapshot.State.Text}' state with exit code '{snapshot.ExitCode}', expected '{exitCode}'."
                    );
            }

            resourceLogger.LogInformation("Finished waiting for resource '{ResourceName}'.", displayName);

View on GitHub (pinned to 25830f84bd)