microsoft/aspire · error · InvalidOperationException

Cannot create a Microsoft Foundry project connection to an…

Error message

Cannot create a Microsoft Foundry project connection to an emulator Cosmos DB instance.

What it means

Microsoft Foundry project connections point at real Azure resources; the Azure Cosmos DB emulator is a local-only endpoint that Foundry cannot reach. AddConnection for Cosmos DB throws this InvalidOperationException when the supplied AzureCosmosDBResource is running as the emulator (RunAsEmulator).

Solutions

Remove RunAsEmulator() from the Cosmos DB resource so a real Azure Cosmos DB account is provisioned.
Only add the Foundry connection when not in emulator mode, e.g. guard on execution context / publish mode.
Point the Foundry project at a separately declared real Cosmos DB resource instead of the emulated one.

Example fix

// before
var cosmos = builder.AddAzureCosmosDB("cosmos").RunAsEmulator();
project.AddConnection(cosmos); // throws

// after
var cosmos = builder.AddAzureCosmosDB("cosmos"); // no RunAsEmulator
project.AddConnection(cosmos);

Defensive patterns

Strategy: validation

Validate before calling

if (!cosmos.IsEmulator())
    project.AddConnection(cosmos);

Try / catch

try { project.AddConnection(cosmos); } catch (InvalidOperationException ex) when (ex.Message.Contains("emulator Cosmos DB")) { /* skip or provision real Cosmos DB */ }

Prevention

Guard all Foundry connection registrations with IsEmulator() checks.
Keep emulated resources for local app consumption and separate real resources for Foundry connections.
Enable Foundry connections only in publish/deploy mode.

When it happens

Trigger: Calling foundryProject.AddConnection(cosmosDb) where cosmosDb is an AzureCosmosDBResource builder on which RunAsEmulator() was called (or the resource otherwise reports IsEmulator()).

Common situations: Running the app host locally with RunAsEmulator on Cosmos DB while also wiring a Foundry project connection; sharing one app model between local dev and deployed scenarios without conditioning the connection.

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

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/Project/ConnectionBuilderExtensions.cs:98

            infrastructure.Add(new ProvisioningOutput("name", typeof(string)) { Value = connection.Name });
            infrastructure.Add(new ProvisioningOutput("id", typeof(string)) { Value = connection.Id });
        }
        var connectionResource = new AzureCognitiveServicesProjectConnectionResource(name, configureInfrastructure, builder.Resource);
        return builder.ApplicationBuilder.AddResource(connectionResource);
    }

    /// <summary>
    /// Adds CosmosDB to a project as a connection
    /// </summary>
    [AspireExportIgnore(Reason = "Raw AzureCosmosDBResource parameters are not ATS-compatible. Use the resource-builder overload instead.")]
    public static IResourceBuilder<AzureCognitiveServicesProjectConnectionResource> AddConnection(
        this IResourceBuilder<AzureCognitiveServicesProjectResource> builder,
        AzureCosmosDBResource db)
    {
        ArgumentNullException.ThrowIfNull(builder);
        if (db.IsEmulator())
        {
            throw new InvalidOperationException("Cannot create a Microsoft Foundry project connection to an emulator Cosmos DB instance.");
        }
        return builder.AddConnection($"connection-{Guid.NewGuid():N}", (infra) => new AadAuthTypeConnectionProperties()
        {
            Category = CognitiveServicesConnectionCategory.CosmosDB,
            Target = db.ConnectionStringOutput.AsProvisioningParameter(infra),
            IsSharedToAll = true,
            Metadata =
            {
                { "ApiType", "Azure" },
                { "ResourceId", db.Id.AsProvisioningParameter(infra) }
            }
        });
    }

    /// <summary>
    /// Adds CosmosDB to a project as a connection
    /// </summary>
    [AspireExport("addCosmosConnection")]

View on GitHub (pinned to 25830f84bd)