{"record":{"id":"a1f1fa34ffd62ffc","repo":"microsoft/aspire","slug":"the-data-explorer-endpoint-is-only-available-when-using-the","errorCode":null,"errorMessage":"The Data Explorer endpoint is only available when using the Linux-based (vNext) Azure Cosmos DB emulator. Call 'RunAsEmulator' instead.","messagePattern":"The Data Explorer endpoint is only available when using the Linux-based \\(vNext\\) Azure Cosmos DB emulator\\. Call 'RunAsEmulator' instead\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs","lineNumber":491,"sourceCode":"    }\n\n    /// <summary>\n    /// Configures the Azure Cosmos DB Linux-based (vNext) emulator to expose the Data Explorer endpoint.\n    /// </summary>\n    /// <param name=\"builder\">Builder for the Cosmos emulator container</param>\n    /// <param name=\"port\">Optional host port to bind the Data Explorer to.</param>\n    /// <returns>Cosmos emulator resource builder.</returns>\n    /// <remarks>\n    /// The separate Data Explorer endpoint configured by this method is only available with <see cref=\"RunAsEmulator(IResourceBuilder{AzureCosmosDBResource}, Action{IResourceBuilder{AzureCosmosDBEmulatorResource}})\"/>.\n    /// </remarks>\n    [AspireExport]\n    public static IResourceBuilder<AzureCosmosDBEmulatorResource> WithDataExplorer(this IResourceBuilder<AzureCosmosDBEmulatorResource> builder, int? port = null)\n    {\n        ArgumentNullException.ThrowIfNull(builder);\n\n        if (!builder.Resource.InnerResource.IsVNextEmulator)\n        {\n            throw new NotSupportedException($\"The Data Explorer endpoint is only available when using the Linux-based (vNext) Azure Cosmos DB emulator. Call '{nameof(RunAsEmulator)}' instead.\");\n        }\n\n        // The vNext image enables the Data Explorer by default, but set ENABLE_EXPLORER explicitly so that\n        // exposing this endpoint does not silently depend on the image's default remaining \"true\".\n        builder.WithEnvironment(\"ENABLE_EXPLORER\", \"true\");\n\n        var result = builder.WithEndpoint(endpointName: KnownUrls.DataExplorer.EndpointName, endpoint =>\n            {\n                endpoint.UriScheme = \"http\";\n                endpoint.TargetPort = 1234;\n                endpoint.Port = port;\n            })\n            .WithUrls(context =>\n            {\n                var url = context.Urls.FirstOrDefault(u => u.Endpoint?.EndpointName == KnownUrls.DataExplorer.EndpointName);\n#pragma warning disable IDE0031 // Use null propagation (IDE0031)\n                if (url is not null)\n#pragma warning restore IDE0031","sourceCodeStart":473,"sourceCodeEnd":509,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Azure.CosmosDB/AzureCosmosDBExtensions.cs#L473-L509","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the default RunAsEmulator configuration so the vNext (Linux) emulator image is selected, then call WithDataExplorer","Remove any explicit emulator image override pinning the legacy Windows emulator","If you truly need the legacy image, remove the WithDataExplorer call and use the legacy emulator's own UI"],"exampleFix":"// before\nvar cosmos = builder.AddAzureCosmosDB(\"cosmos\")\n    .RunAsEmulator(e => e.WithImageTag(\"mcr.microsoft.com/cosmosdb/windows/azure-cosmos-db-emulator\"))\n    .AddDataExplorer();\n// after\nvar cosmos = builder.AddAzureCosmosDB(\"cosmos\")\n    .RunAsEmulator()\n    .WithDataExplorer();","handlingStrategy":"validation","validationCode":"if (!Enum.IsDefined(typeof(KnownEmulatorImages), imageTag)) { /* confirm image supports Data Explorer before calling WithDataExplorer */ }","typeGuard":null,"tryCatchPattern":"try { builder.WithDataExplorer(); }\ncatch (NotSupportedException ex) { logger.LogWarning(ex, \"Data Explorer unavailable for this emulator image\"); }","preventionTips":["Don't override the emulator image tag unless necessary","Check release notes when upgrading Aspire for emulator image changes","Call RunAsEmulator with defaults when you need WithDataExplorer"],"tags":["cosmosdb","emulator","data-explorer","unsupported"],"backgroundTag":"unsupported-operation","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T09:17:21.228Z"}