microsoft/aspire · error · InvalidOperationException

Dashboard endpoint is only available when running as an…

Error message

Dashboard endpoint is only available when running as an emulator.

What it means

The Durable Task Scheduler resource in Aspire.Hosting.Azure.Functions exposes a dashboard endpoint URL, but that endpoint is only provisioned when the scheduler resource runs in emulator mode. Accessing the dashboard endpoint property on a non-emulator (real Azure) scheduler resource throws this InvalidOperationException, since no local dashboard is hosted.

Solutions

Configure the scheduler resource for local development with .RunEmulator() so the dashboard endpoint exists.
Guard dashboard URL access: only read the endpoint when the resource is in emulator mode (check the emulator flag/configuration before calling).
If targeting a real scheduler, use the Azure-hosted Durable Task Dashboard instead of the Aspire-provided emulator endpoint.

Example fix

// before
var dashboardUrl = schedulerResource.EmulatorDashboardEndpoint();

// after
if (schedulerIsEmulator)
{
    var dashboardUrl = schedulerResource.EmulatorDashboardEndpoint();
}
else
{
    // use the Azure portal dashboard for the real scheduler
}

Defensive patterns

Strategy: validation

Validate before calling

if (!schedulerResource.IsEmulator) // or check the RunEmulator flag/config
{
    throw new InvalidOperationException("Dashboard endpoint requires emulator mode; call .RunEmulator() for local dev.");
}
var dashboardUrl = schedulerResource.EmulatorDashboardEndpoint();

Prevention

Only call EmulatorDashboardEndpoint in local-development code paths gated on emulator mode.
Centralize dashboard URL retrieval behind a helper that checks the mode once.
When migrating from emulator to real scheduler, audit all dashboard URL consumers.

When it happens

Trigger: Calling the dashboard endpoint URL expression (via EmulatorDashboardEndpoint / CreateDashboardEndpoint) on a DurableTaskSchedulerResource that was NOT configured with .RunEmulator(), e.g. when pointing at a real Azure Durable Task Scheduler instance.

Common situations: Developers build locally against a real scheduler instead of the emulator, or switch from emulator mode to production mode and existing code that read the dashboard URL keeps executing; apps that unconditionally render or pass the dashboard URL fail at model build time.

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

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Functions/DurableTask/DurableTaskSchedulerResource.cs:61

                ParameterResource parameterResource => ReferenceExpression.Create($"{parameterResource}"),
                string value => ReferenceExpression.Create($"{value}"),
                _ => throw new InvalidOperationException($"Unexpected connection string type: {connectionStringAnnotation.ConnectionString.GetType().Name}"),
            };
        }

        throw new InvalidOperationException($"Unable to resolve the Durable Task Scheduler connection string. Configure the scheduler using {nameof(DurableTaskResourceExtensions.RunAsEmulator)}() or {nameof(DurableTaskResourceExtensions.RunAsExisting)}(connectionString) before accessing {nameof(ConnectionStringExpression)}.");
    }

    private ReferenceExpression CreateDashboardEndpoint()
    {
        if (IsEmulator)
        {
            var dashboardEndpoint = new EndpointReference(this, "dashboard");

            return ReferenceExpression.Create($"{dashboardEndpoint.Property(EndpointProperty.Url)}");
        }

        throw new InvalidOperationException("Dashboard endpoint is only available when running as an emulator.");
    }
}

View on GitHub (pinned to 25830f84bd)