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 Container Registry

What it means

Foundry project connections to a container registry need an actual Azure Container Registry endpoint. AddConnection for Container Registry throws this InvalidOperationException when the supplied AzureContainerRegistryResource runs as an emulator, which Foundry cannot use as a connection target.

Solutions

Remove RunAsEmulator() from the Container Registry resource.
Guard the connection call so it only runs for non-emulated registry resources.
Provision a real Azure Container Registry for the Foundry project connection.

Example fix

// before
var registry = builder.AddAzureContainerRegistry("acr").RunAsEmulator();
project.AddConnection(registry); // throws

// after
var registry = builder.AddAzureContainerRegistry("acr");
project.AddConnection(registry);

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try { project.AddConnection(registry); } catch (InvalidOperationException ex) when (ex.Message.Contains("emulator Container Registry")) { /* skip or provision real ACR */ }

Prevention

Check registry.IsEmulator() before wiring the connection.
Do not emulate a registry that the Foundry project must connect to.
Centralize emulator decisions in one place so connection wiring can consult them.

When it happens

Trigger: Calling foundryProject.AddConnection(registry) where the AzureContainerRegistryResource builder had RunAsEmulator() applied (registry.IsEmulator() returns true).

Common situations: Local test configurations emulating ACR; reusing a shared emulated registry resource across the app model while wiring Foundry connections.

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/3f59a1b90f8930fd. Report an issue: GitHub.

Appendix: source

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

    {
        builder.WithRoleAssignments(storage, StorageBuiltInRole.StorageBlobDataContributor);
        return builder.AddConnection(storage.Resource);
    }

    /// <summary>
    /// Adds a container registry connection to the Microsoft Foundry project.
    /// </summary>
    /// <returns></returns>
    [AspireExportIgnore(Reason = "Raw AzureContainerRegistryResource parameters are not ATS-compatible. Use the resource-builder overload instead.")]
    public static IResourceBuilder<AzureCognitiveServicesProjectConnectionResource> AddConnection(
        this IResourceBuilder<AzureCognitiveServicesProjectResource> builder,
        AzureContainerRegistryResource registry)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(registry);
        if (registry.IsEmulator())
        {
            throw new InvalidOperationException("Cannot create a Microsoft Foundry project connection to an emulator Container Registry");
        }
        return builder.AddConnection($"connection-{Guid.NewGuid():N}", (infra) => new ManagedIdentityAuthTypeConnectionProperties()
        {
            Category = CognitiveServicesConnectionCategory.ContainerRegistry,
            Target = registry.RegistryEndpoint.AsProvisioningParameter(infra),
            IsSharedToAll = true,
            Credentials = new CognitiveServicesConnectionManagedIdentity(){
                ClientId = "aiprojectidentityprincipleaid",
                ResourceId = registry.NameOutputReference.AsProvisioningParameter(infra)
            },
            Metadata =
            {
                { "ApiType", "Azure" },
                { "ResourceId", registry.NameOutputReference.AsProvisioningParameter(infra) }
            }
        });
    }

View on GitHub (pinned to 25830f84bd)