microsoft/aspire · error · InvalidOperationException

Microsoft Foundry projects are not supported when the…

Error message

Microsoft Foundry projects are not supported when the parent Foundry resource is configured with RunAsFoundryLocal().

What it means

When the parent Foundry resource is configured with RunAsFoundryLocal(), it runs the Foundry Local emulator, which cannot host Foundry projects. AddProject checks builder.Resource.IsEmulator and throws this InvalidOperationException (FoundryExtensions.LocalProjectsNotSupportedMessage) when a project resource is added in that mode.

Solutions

1. Remove RunAsFoundryLocal() so the Foundry resource provisions real projects in Azure.
2. Only call AddProject when the parent Foundry resource is not running as Foundry Local (guard on builder.Resource.IsEmulator or execution context).
3. Use Foundry Local's own APIs/models directly instead of Foundry projects for the emulated scenario.

Example fix

// before
var foundry = builder.AddAzureFoundry("foundry").RunAsFoundryLocal();
foundry.AddProject("agent-project"); // throws

// after
var foundry = builder.AddAzureFoundry("foundry"); // no RunAsFoundryLocal
foundry.AddProject("agent-project");

if (!foundry.Resource.IsEmulator)
    foundry.AddProject("agent-project");

try { foundry.AddProject(name); } catch (InvalidOperationException ex) when (ex.Message.Contains("RunAsFoundryLocal")) { /* switch to real provisioning or use Foundry Local APIs */ }

When it happens

Trigger: Calling foundry.AddFoundryLocal(...) / RunAsFoundryLocal() on the parent Foundry resource and then calling foundry.AddProject("name") to add a project resource to it.

Common situations: Local development configured for Foundry Local while sample code also adds projects; mixing emulator-based local setups with project-based deployment models in one app model.

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

• Cannot create a Microsoft Foundry project connection to an…
• Cannot create a Microsoft Foundry project connection to an…
• Cannot create a Microsoft Foundry project connection to an…
• Cannot create a Microsoft Foundry project connection to an…
• BlobServiceClient is not initialized.

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/Project/ProjectBuilderExtension.cs:47

    /// <summary>
    /// Adds a Microsoft Foundry project resource to the application model.
    ///
    /// This will also attach the project as a deployment target for agents.
    /// </summary>
    /// <param name="builder">The <see cref="IResourceBuilder{T}"/> for the parent Microsoft Foundry account resource.</param>
    /// <param name="name">The name of the Microsoft Foundry project resource.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/> for the Microsoft Foundry project resource.</returns>
    /// <ats-returns>The resource builder.</ats-returns>
    [AspireExport]
    public static IResourceBuilder<AzureCognitiveServicesProjectResource> AddProject(
        this IResourceBuilder<FoundryResource> builder,
        [ResourceName] string name)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentException.ThrowIfNullOrEmpty(name);
        if (builder.Resource.IsEmulator)
        {
            throw new InvalidOperationException(FoundryExtensions.LocalProjectsNotSupportedMessage);
        }

        builder.ApplicationBuilder.Services.Configure<AzureProvisioningOptions>(o => o.SupportsTargetedRoleAssignments = true);

        var project = builder.ApplicationBuilder.AddResource(new AzureCognitiveServicesProjectResource(name, ConfigureInfrastructure, builder.Resource));
        if (builder.ApplicationBuilder.ExecutionContext.IsPublishMode)
        {
            project.Resource.DefaultContainerRegistry = CreateDefaultRegistry(builder.ApplicationBuilder, $"{name}-acr");
        }

        return project;
    }

    /// <summary>
    /// Adds a reference to a Microsoft Foundry project resource to the destination resource.
    /// </summary>
    /// <remarks>This overload is not available in polyglot app hosts. Use the standard <c>WithReference</c> overload instead.</remarks>
    [AspireExportIgnore(Reason = "The standard WithReference export already covers this polyglot scenario.")]

View on GitHub (pinned to 25830f84bd)