microsoft/aspire · error · DistributedApplicationException

The MAUI OTLP protocol could not be determined because the…

Error message

The MAUI OTLP protocol could not be determined because the dashboard did not publish a concrete OTLP listener within {resolutionTimeout:c}.

What it means

The OTLP transport protocol (grpc vs protobuf/http) for MAUI telemetry could not be determined because the dashboard resource never published a concrete OTLP listener within the timeout. The code waits for the dashboard endpoint snapshot with WaitAsync(resolutionTimeout); on TimeoutException it throws this DistributedApplicationException.

Solutions

Increase resolutionTimeout to allow the dashboard to publish its endpoint.
Confirm the dashboard resource starts and listens (check its logs and published endpoints).
Rule out dashboard disablement via environment/configuration in the current run.
Retry after the dashboard is healthy; the protocol is derived from the published endpoint.

Example fix

// before
var protocol = await otlpProtocol.GetValueAsync(ct); // times out on cold start
// after
// wait for dashboard health first, then resolve, or raise the timeout
dashboardOptions.ResolutionTimeout = TimeSpan.FromMinutes(2);

Defensive patterns

Strategy: try-catch

Validate before calling

// Wait for a healthy dashboard snapshot before asking for the protocol
var dashboardHealthy = await dashboardRef.WaitUntilHealthyAsync(TimeSpan.FromMinutes(2), ct);

Type guard

static bool HasConcreteEndpoint(ResourceEvent e) =>
    !string.IsNullOrEmpty(e.Snapshot?.Properties?.FirstOrDefault(p => p.Name is "otlpendpoint" or "endpoint")?.Value?.ToString());

Try / catch

try
{
    var protocol = await otlpProtocolValue.GetValueAsync(ct);
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("OTLP protocol could not be determined"))
{
    protocol = OtlpProtocol.Grpc; // known dashboard default, or rethrow with context
}

Prevention

Confirm the dashboard resource starts before MAUI resources that need OTLP
Raise resolutionTimeout on image-pull-heavy or CI environments
Do not set environment variables that disable or relocate the dashboard endpoint unexpectedly
Retry resolution after the dashboard becomes healthy instead of failing the whole AppHost

When it happens

Trigger: Requesting the MAUI OTLP protocol while the dashboard resource fails to publish a concrete endpoint snapshot before resolutionTimeout expires — dashboard slow, failed, or absent.

Common situations: Dashboard container still pulling its image, dashboard crashed on startup, endpoint metadata not yet materialized during rapid app startup, or the timeout is too aggressive on constrained CI machines.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Maui/MauiOtlpExtensions.cs:615

    private sealed class OtlpProtocolValueProvider(
        EndpointAnnotation endpoint,
        TimeSpan resolutionTimeout) : IValueProvider
    {
        public async ValueTask<string?> GetValueAsync(CancellationToken cancellationToken = default)
        {
            try
            {
#pragma warning disable CS0618 // Type or member is obsolete
                await endpoint.AllocatedEndpointSnapshot
                    .GetValueAsync(cancellationToken)
                    .WaitAsync(resolutionTimeout, cancellationToken)
                    .ConfigureAwait(false);
#pragma warning restore CS0618 // Type or member is obsolete
            }
            catch (TimeoutException ex)
            {
                throw new DistributedApplicationException(
                    $"The MAUI OTLP protocol could not be determined because the dashboard did not publish a concrete OTLP listener within {resolutionTimeout:c}.",
                    ex);
            }

            return GetOtlpProtocol(endpoint);
        }
    }
}

View on GitHub (pinned to 25830f84bd)