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 prematurely.

What it means

Thrown by WaitUntilStateAsync when, under StopOnResourceUnavailable behavior, the dependency resource enters a terminal/unavailable state (Finished, Exited, RuntimeUnhealthy) before reaching the awaited state. Aspire aborts the wait with a message identifying the premature state.

Solutions

1. Check dependency logs for the reason it exited or became runtime-unhealthy.
2. If the dependency is a batch job, replace WaitFor/WaitUntilHealthy with WaitForCompletion and an expected exit code.
3. Fix health configuration (health checks, probes, resource limits) that causes RuntimeUnhealthy.
4. Use WaitBehavior.WaitOnResourceUnavailable if the dependency legitimately cycles and you want to keep waiting.

Example fix

// before
builder.AddProject<Projects.Worker>("worker")
    .WaitFor("seeder"); // seeder is a one-shot job that exits

// after
builder.AddProject<Projects.Worker>("worker")
    .WaitForCompletion("seeder", exitCode: 0);

// Only wait for Running/Healthy on resources designed to stay up; for one-shot jobs use:
// builder.WaitForCompletion(name, exitCode: 0);

try
{
    await app.StartAsync();
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("prematurely"))
{
    logger.LogError(ex, "Dependency exited before reaching the awaited state.");
}

When it happens

Trigger: WaitFor/WaitUntilHealthy/WaitUntilStarted with WaitBehavior.StopOnResourceUnavailable while the dependency transitions to Finished, Exited, or RuntimeUnhealthy before becoming Running/Healthy.

Common situations: Dependency process exits early after a crash; runtime health checks (e.g. container liveness) mark the resource RuntimeUnhealthy; dependency is a short-lived job being awaited with a healthy-state wait instead of WaitForCompletion.

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

• Circular dependency detected
• ConnectionStringAvailableEvent published for resource
• Failed to send request
• Resource ' ' stopped waiting for dependency resource ' '…
• Resource ' ' stopped waiting for dependency resource ' '…

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

Appendix: source

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

                {
                    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.State.Text == KnownResourceStates.RuntimeUnhealthy)
                {
                    resourceLogger.LogError(
                        "Resource '{ResourceName}' has entered the '{State}' state prematurely.",
                        displayName,
                        snapshot.State.Text
                        );

                    throw new DistributedApplicationException(
                        $"Resource '{resource.Name}' stopped waiting for dependency resource '{displayName}' because it entered the '{snapshot.State.Text}' state prematurely."
                        );
                }
            }

            // Execute the post-running action specific to the wait type
            await postRunningAction(resourceLogger, displayName, resourceId, resourceEvent).ConfigureAwait(false);

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

            static bool IsContinuableState(WaitBehavior waitBehavior, CustomResourceSnapshot snapshot) =>
                waitBehavior switch
                {
                    WaitBehavior.WaitOnResourceUnavailable => snapshot.State?.Text == KnownResourceStates.Running,
                    WaitBehavior.StopOnResourceUnavailable => snapshot.State?.Text == KnownResourceStates.Running ||

View on GitHub (pinned to 25830f84bd)