microsoft/aspire · error · DistributedApplicationException

Unexpected wait type

Error message

Unexpected wait type: {waitAnnotation.WaitType}

What it means

Exhaustiveness guard in WaitForDependenciesAsync: a WaitAnnotation had a WaitType other than WaitUntilHealthy, WaitForCompletion, or WaitUntilStarted. The switch throws DistributedApplicationException for the unknown wait type.

Solutions

1. Only construct wait annotations with the three supported WaitType members: WaitUntilHealthy, WaitForCompletion, WaitUntilStarted.
2. Remove numeric casts/default(WaitType) in custom annotation code.
3. Align Aspire.Hosting package versions between the AppHost and any custom extension libraries.

Example fix

// before
var wait = new WaitAnnotation(dep, (WaitType)99);

// after
var wait = new WaitAnnotation(dep, WaitType.WaitUntilStarted);

static bool IsSupportedWaitType(WaitType t) =>
    t is WaitType.WaitUntilHealthy or WaitType.WaitForCompletion or WaitType.WaitUntilStarted;
if (!IsSupportedWaitType(annotation.WaitType)) throw new ArgumentException($"Unsupported WaitType: {annotation.WaitType}");

static bool IsDefinedWaitType(WaitType value) =>
    value is WaitType.WaitUntilHealthy or WaitType.WaitForCompletion or WaitType.WaitUntilStarted;

try
{
    await app.StartAsync();
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("Unexpected wait type"))
{
    logger.LogError(ex, "Invalid WaitType in a WaitAnnotation.");
}

When it happens

Trigger: Custom code (or a mismatched extension package) constructing a WaitAnnotation with an undefined or unsupported WaitType value, which then flows through WaitForDependenciesAsync during resource start orchestration.

Common situations: Casting ints to WaitType in custom resource extensions; Aspire.Hosting version drift where a newer WaitType member is consumed by older hosting code; hand-written annotations copied with wrong enum values.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unexpected wait behavior
• ConnectionStringAvailableEvent was published for the
• Container tunnel service
• Invalid entrypoint type.
• Service should have valid address at this point

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

Appendix: source

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

                    }
                    else
                    {
                        await ClearWaitingForDependenciesAsync(resource).ConfigureAwait(false);
                    }
                }
                finally
                {
                    pendingDependencyLock.Release();
                }
            }

            var pendingDependencies = waitAnnotationsToProcess
                .Select(waitAnnotation => waitAnnotation.WaitType switch
                {
                    WaitType.WaitUntilHealthy => WaitUntilHealthyAsync(resource, waitAnnotation.Resource, waitAnnotation.WaitBehavior ?? DefaultWaitBehavior, cancellationToken, OnDependencyReadyAsync),
                    WaitType.WaitForCompletion => WaitUntilCompletionAsync(resource, waitAnnotation.Resource, waitAnnotation.ExitCode, cancellationToken, OnDependencyReadyAsync),
                    WaitType.WaitUntilStarted => WaitUntilStartedAsync(resource, waitAnnotation.Resource, waitAnnotation.WaitBehavior ?? DefaultWaitBehavior, cancellationToken, OnDependencyReadyAsync),
                    _ => throw new DistributedApplicationException($"Unexpected wait type: {waitAnnotation.WaitType}")
                });

            await Task.WhenAll(pendingDependencies).ConfigureAwait(false);

            var clearRemainingDependencies = false;
            await pendingDependencyLock.WaitAsync(CancellationToken.None).ConfigureAwait(false);
            try
            {
                clearRemainingDependencies = pendingDependencyCounts.Count > 0;
                pendingDependencyCounts.Clear();
            }
            finally
            {
                pendingDependencyLock.Release();
            }

            if (clearRemainingDependencies)
            {

View on GitHub (pinned to 25830f84bd)