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

Foundry project (AzureCognitiveServicesProjectResource) child resources rely on Azure cloud behavior that Foundry Local emulation does not provide. When RunAsFoundryLocal is called on a parent Foundry resource that already has project resources attached, Aspire throws this InvalidOperationException because projects cannot run in local mode.

Solutions

1. Remove the AzureCognitiveServicesProjectResource children before switching the parent to RunAsFoundryLocal
2. Keep the parent in Azure mode (don't call RunAsFoundryLocal) if projects are required
3. Move project deployments to a separate Foundry resource that stays in Azure mode

Example fix

// before
var foundry = builder.AddFoundry("foundry")
    .AddProject("proj");
foundry.RunAsFoundryLocal(); // throws
// after
var foundry = builder.AddFoundry("foundry").AddProject("proj"); // stays in Azure mode

bool hasProjects = builder.ApplicationBuilder.Resources
    .OfType<AzureCognitiveServicesProjectResource>()
    .Any(p => ReferenceEquals(p.Parent, foundry.Resource));
if (hasProjects) { /* don't call RunAsFoundryLocal */ }

try { foundry.RunAsFoundryLocal(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("not supported")) { /* remove project children or stay in Azure mode */ }

When it happens

Trigger: Adding a project via .AddProject(...) on a Foundry resource and later calling .RunAsFoundryLocal() on the same Foundry resource builder.

Common situations: Enabling local development mode on an existing app model that already wires Foundry projects; experimenting with RunAsFoundryLocal without removing child projects.

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

• aspire: GetValue is only available on server-returned…
• Bind mounts are not supported by the Kubernetes publisher
• Bun apps cannot be debugged through the Node dev-server…
• Cannot remove '"))} from the existing MongoDB replica set '…
• Channel ' ' does not support CLI downloads.

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/FoundryExtensions.cs:268

                    timeout: default
                    ));
        builder.ApplicationBuilder.Services.AddHttpClient(nameof(FoundryLocalHealthCheck), client =>
            client.Timeout = s_healthCheckTimeout);
        builder.ApplicationBuilder.Services.AddHttpClient(nameof(LocalModelHealthCheck), client =>
            client.Timeout = s_healthCheckTimeout);

        builder.WithHealthCheck(healthCheckKey);

        return builder;
    }

    internal static void ThrowIfProjectsConfiguredForLocal(IResourceBuilder<FoundryResource> builder, FoundryResource resource)
    {
        if (builder.ApplicationBuilder.Resources
            .OfType<AzureCognitiveServicesProjectResource>()
            .Any(project => ReferenceEquals(project.Parent, resource)))
        {
            throw new InvalidOperationException(LocalProjectsNotSupportedMessage);
        }
    }

    /// <summary>
    /// Assigns the specified roles to the given resource, granting it the necessary permissions
    /// on the target Microsoft Foundry resource. This replaces the default role assignments for the resource.
    /// </summary>
    /// <param name="builder">The resource to which the specified roles will be assigned.</param>
    /// <param name="target">The target Microsoft Foundry resource.</param>
    /// <param name="roles">The built-in Cognitive Services roles to be assigned.</param>
    /// <returns>The updated <see cref="IResourceBuilder{T}"/> with the applied role assignments.</returns>
    /// <remarks>
    /// <example>
    /// Assigns the CognitiveServicesOpenAIContributor role to the 'Projects.Api' project.
    /// <code lang="csharp">
    /// var builder = DistributedApplication.CreateBuilder(args);
    ///
    /// var aiFoundry = builder.AddFoundry("aiFoundry");

View on GitHub (pinned to 25830f84bd)