microsoft/aspire · error · InvalidOperationException

Microsoft Foundry project resource

Error message

Microsoft Foundry project resource '{builder.Resource.Name}' does not have a capability host configured. Call addCapabilityHost first.

What it means

The internal WithCapabilityHost* setters (CosmosDB/Storage/Search/AzureOpenAI) require that a capability host configuration already exists on the Foundry project resource, created by AddCapabilityHost. GetCapabilityHostConfiguration throws this InvalidOperationException when CapabilityHostConfiguration is still null.

Solutions

Call project.AddCapabilityHost("name") (or addCapabilityHost) before the WithCapabilityHost* calls
Ensure the same IResourceBuilder<AzureCognitiveServicesProjectResource> instance is used for both calls
Chain the calls off the result of AddCapabilityHost so the config exists

Example fix

// before
project.WithCapabilityHostCosmosDB(cosmosDb);

// after
project.AddCapabilityHost("cap-host").WithCapabilityHostCosmosDB(cosmosDb);

Defensive patterns

Strategy: validation

Validate before calling

var capHost = project.AddCapabilityHost("cap-host");
capHost.WithCapabilityHostCosmosDB(cosmosDb); // config now exists

Try / catch

try { project.WithCapabilityHostCosmosDB(cosmosDb); }
catch (InvalidOperationException ex) when (ex.Message.Contains("does not have a capability host configured"))
{
    // Call AddCapabilityHost first.
}

Prevention

Always start capability-host configuration with AddCapabilityHost
Chain With* calls off the AddCapabilityHost result
Use the same builder instance throughout configuration

When it happens

Trigger: Calling a WithCapabilityHostCosmosDB/Storage/Search/AzureOpenAI extension directly without first calling AddCapabilityHost (or the exported addCapabilityHost) on the same project builder.

Common situations: Using internal APIs in tests or extensions and skipping the initialization call; calling the setters on a different project builder instance than the one AddCapabilityHost was called on; refactor that removed the AddCapabilityHost call.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

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

    private static AzureContainerRegistryResource CreateDefaultRegistry(IDistributedApplicationBuilder builder, string name)
    {
        var resource = new AzureContainerRegistryResource(name, ContainerRegistryInfrastructure.ConfigureContainerRegistry);
        builder.AddResource(resource).WithIconName("Archive");
        return resource;
    }

    private static CapabilityHostConfiguration CreateCapabilityHostConfiguration(
        IResourceBuilder<AzureCognitiveServicesProjectResource> builder,
        string name)
    {
        var config = new CapabilityHostConfiguration(name);
        builder.Resource.CapabilityHostConfiguration = config;
        return config;
    }

    private static CapabilityHostConfiguration GetCapabilityHostConfiguration(IResourceBuilder<AzureCognitiveServicesProjectResource> builder)
        => builder.Resource.CapabilityHostConfiguration
            ?? throw new InvalidOperationException($"Microsoft Foundry project resource '{builder.Resource.Name}' does not have a capability host configured. Call addCapabilityHost first.");
}

View on GitHub (pinned to 25830f84bd)