microsoft/aspire · error · NotSupportedException

The Data Explorer endpoint is only available when using the…

Error message

The Data Explorer endpoint is only available when using the Linux-based (vNext) Azure Cosmos DB emulator. Call 'RunAsEmulator' instead.

What it means

WithDataExplorer exposes the Data Explorer UI endpoint, but that feature only exists in the Linux-based (vNext) Cosmos DB emulator image. The older Windows emulator image does not serve Data Explorer, so the extension throws NotSupportedException instead of silently adding a broken endpoint.

Solutions

1. Use the default RunAsEmulator configuration so the vNext (Linux) emulator image is selected, then call WithDataExplorer
2. Remove any explicit emulator image override pinning the legacy Windows emulator
3. If you truly need the legacy image, remove the WithDataExplorer call and use the legacy emulator's own UI

Example fix

// before
var cosmos = builder.AddAzureCosmosDB("cosmos")
    .RunAsEmulator(e => e.WithImageTag("mcr.microsoft.com/cosmosdb/windows/azure-cosmos-db-emulator"))
    .AddDataExplorer();
// after
var cosmos = builder.AddAzureCosmosDB("cosmos")
    .RunAsEmulator()
    .WithDataExplorer();

if (!Enum.IsDefined(typeof(KnownEmulatorImages), imageTag)) { /* confirm image supports Data Explorer before calling WithDataExplorer */ }

try { builder.WithDataExplorer(); }
catch (NotSupportedException ex) { logger.LogWarning(ex, "Data Explorer unavailable for this emulator image"); }

When it happens

Trigger: Calling .WithDataExplorer() on a CosmosDB emulator resource when the underlying emulator is the legacy Windows image — e.g. RunAsEmulator was configured without switching to the vNext (Linux) image, or an older image tag is pinned.

Common situations: Upgraded Aspire but kept an emulator image override pointing at the classic mcr.microsoft.com/cosmosdb/windows/azure-cosmos-db-emulator image; copied older sample code that predates the vNext emulator.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• ConnectionStringAvailableEvent was published for the
• CosmosClient is not initialized.
• Count must be between 1 and 250.
• Emulator currently does not support data lake.
• Value cannot be null. (Parameter 'innerResource')

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs:491

    }

    /// <summary>
    /// Configures the Azure Cosmos DB Linux-based (vNext) emulator to expose the Data Explorer endpoint.
    /// </summary>
    /// <param name="builder">Builder for the Cosmos emulator container</param>
    /// <param name="port">Optional host port to bind the Data Explorer to.</param>
    /// <returns>Cosmos emulator resource builder.</returns>
    /// <remarks>
    /// The separate Data Explorer endpoint configured by this method is only available with <see cref="RunAsEmulator(IResourceBuilder{AzureCosmosDBResource}, Action{IResourceBuilder{AzureCosmosDBEmulatorResource}})"/>.
    /// </remarks>
    [AspireExport]
    public static IResourceBuilder<AzureCosmosDBEmulatorResource> WithDataExplorer(this IResourceBuilder<AzureCosmosDBEmulatorResource> builder, int? port = null)
    {
        ArgumentNullException.ThrowIfNull(builder);

        if (!builder.Resource.InnerResource.IsVNextEmulator)
        {
            throw new NotSupportedException($"The Data Explorer endpoint is only available when using the Linux-based (vNext) Azure Cosmos DB emulator. Call '{nameof(RunAsEmulator)}' instead.");
        }

        // The vNext image enables the Data Explorer by default, but set ENABLE_EXPLORER explicitly so that
        // exposing this endpoint does not silently depend on the image's default remaining "true".
        builder.WithEnvironment("ENABLE_EXPLORER", "true");

        var result = builder.WithEndpoint(endpointName: KnownUrls.DataExplorer.EndpointName, endpoint =>
            {
                endpoint.UriScheme = "http";
                endpoint.TargetPort = 1234;
                endpoint.Port = port;
            })
            .WithUrls(context =>
            {
                var url = context.Urls.FirstOrDefault(u => u.Endpoint?.EndpointName == KnownUrls.DataExplorer.EndpointName);
#pragma warning disable IDE0031 // Use null propagation (IDE0031)
                if (url is not null)
#pragma warning restore IDE0031

View on GitHub (pinned to 25830f84bd)