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 Key Vault.

What it means

Foundry project connections to Key Vault require a real vault. AddConnection for Key Vault throws this InvalidOperationException when the supplied AzureKeyVaultResource is emulated (keyVault.Resource.IsEmulator()), because the Foundry service cannot authenticate to a local fake vault.

Solutions

Remove RunAsEmulator() from the Key Vault resource so a real vault is provisioned.
Add the connection conditionally, skipping it when the vault is emulated.
Declare a separate non-emulated Key Vault resource as the connection target.

Example fix

// before
var kv = builder.AddAzureKeyVault("kv").RunAsEmulator();
project.AddConnection(kv); // throws

// after
var kv = builder.AddAzureKeyVault("kv");
project.AddConnection(kv);

Defensive patterns

Strategy: validation

Validate before calling

if (!keyVault.Resource.IsEmulator())
    project.AddConnection(keyVault);

Try / catch

try { project.AddConnection(keyVault); } catch (InvalidOperationException ex) when (ex.Message.Contains("emulator Key Vault")) { /* skip or provision real Key Vault */ }

Prevention

Check keyVault.Resource.IsEmulator() before adding the connection.
Remember AddConnection also applies role assignments (KeyVaultSecretsOfficer), which only makes sense for real vaults.
Condition emulation on execution context rather than hardcoding RunAsEmulator.

When it happens

Trigger: Calling foundryProject.AddConnection(keyVault) where the AzureKeyVaultResource was created with RunAsEmulator() so keyVault.Resource.IsEmulator() is true.

Common situations: Local development with an emulated Key Vault combined with Foundry connection wiring; sample apps that default vaults to emulator mode.

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/396f145c3f2eda64. Report an issue: GitHub.

Appendix: source

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

    /// <summary>
    /// Adds a Key Vault connection to the Microsoft Foundry project.
    /// </summary>
    /// <remarks>
    /// This connection allows the Microsoft Foundry project to store secrets for various other connections.
    /// As such, we recommend adding this connection *before* any others, so that those connections
    /// can leverage the Key Vault connection for secret storage.
    /// </remarks>
    [AspireExport("addKeyVaultConnection")]
    public static IResourceBuilder<AzureCognitiveServicesProjectConnectionResource> AddConnection(
        this IResourceBuilder<AzureCognitiveServicesProjectResource> builder,
        IResourceBuilder<AzureKeyVaultResource> keyVault)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(keyVault);
        if (keyVault.Resource.IsEmulator())
        {
            throw new InvalidOperationException("Cannot create a Microsoft Foundry project connection to an emulator Key Vault.");
        }
        builder.WithRoleAssignments(keyVault, KeyVaultBuiltInRole.KeyVaultSecretsOfficer);
        // Configuration based on https://github.com/azure-ai-foundry/foundry-samples/blob/9551912af4d4fdb8ea73e996145e940a7e369c84/infrastructure/infrastructure-setup-bicep/01-connections/connection-key-vault.bicep
        // We use a custom subclass because Azure.Provisioning.CognitiveServices does not support the "AzureKeyVault" connection category yet (as of 2026-01-06).
        // We also swap `ManagedIdentity` auth type for `AccountManagedIdentity`, because the latter seems to be an error in the Bicep template.
        return builder.AddConnection($"{keyVault.Resource.Name}-{Guid.NewGuid():N}", (infra) =>
        {
            var vault = (KeyVaultService)keyVault.Resource.AddAsExistingResource(infra);
            return new AzureKeyVaultConnectionProperties()
            {
                Target = vault.Id,
                IsSharedToAll = true,
                Metadata =
                {
                    { "ApiType", "Azure" },
                    { "ResourceId", vault.Id },
                    { "location", vault.Location }
                }

View on GitHub (pinned to 25830f84bd)