microsoft/aspire · error · DistributedApplicationException

Resource ' ' stopped waiting for dependency resource ' '…

Error message

Resource '{resource.Name}' stopped waiting for dependency resource '{displayName}' because it entered the '{snapshot.State.Text}' state with exit code '{snapshot.ExitCode}', expected '{exitCode}'.

What it means

Thrown by WaitUntilCompletionAsync when the dependency resource terminates (Finished/Exited) but its exit code differs from the expected exit code passed to WaitForCompletion. Aspire stops waiting because the completion condition can never be satisfied.

Solutions

Read the dependency's exit code from the error message and its logs to diagnose why it exited abnormally.
Correct the dependency's failure (args, connection string, environment).
If the new exit code is legitimate, update the expected exitCode argument to match.
If any nonzero code indicates failure and any zero means success, keep WaitForCompletion with the standard 0 expectation and fix the root cause.

Example fix

// before
builder.AddProject<Projects.Api>("api")
    .WaitForCompletion("migrator", exitCode: 0); // migrator exits 2

// after: fix the migrator (e.g. correct connection string) or accept its real success code
builder.AddProject<Projects.Api>("api")
    .WaitForCompletion("migrator", exitCode: 2); // only if 2 is now the documented success code

Defensive patterns

Strategy: validation

Validate before calling

// Run the job once manually and confirm its success exit code matches the expectation
// var expectedExitCode = 0; // verify with: dotnet run --project migrator; echo $?

Try / catch

try
{
    await app.StartAsync();
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("exit code"))
{
    logger.LogError(ex, "Dependency exited with an unexpected exit code.");
}

Prevention

Verify the job's documented success exit code before hardcoding exitCode in WaitForCompletion.
Diagnose nonzero exit codes from dependency logs before changing expectations.
Keep jobs deterministic: validate connection strings and args before run.
Avoid swallowing exit-code mismatches; they usually indicate a real job failure.

When it happens

Trigger: resource.WaitForCompletion(name, exitCode: N) where the dependency process exits with a code other than N (commonly a nonzero crash code).

Common situations: A migration or seeding job crashes with a nonzero exit code; the expected exit code assumption changed (tool now returns 0 or a different sentinel code); dependency fails due to bad arguments or DB connection errors.

Related errors

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

Appendix: source

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

            {
                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);

            if (onDependencyReady is not null)
            {
                await onDependencyReady(resourceId).ConfigureAwait(false);
            }

            static bool IsKnownTerminalState(CustomResourceSnapshot snapshot) =>
                KnownResourceStates.TerminalStates.Contains(snapshot.State?.Text) ||
                snapshot.ExitCode is not null;
        }
    }

    private async Task WaitUntilStateAsync(IResource resource, IResource dependency, WaitBehavior waitBehavior,

View on GitHub (pinned to 25830f84bd)