microsoft/aspire · error · InvalidOperationException

Capability host ' ' on project ' ' requires a CosmosDB…

Error message

Capability host '{Name}' on project '{projectName}' requires a CosmosDB resource. Call WithCosmosDB() on the capability host builder.

What it means

A capability host on a Foundry project requires CosmosDB (and Storage/Search) backing resources. The internal Validate method, run when the capability host is finalized, throws this InvalidOperationException if the CosmosDB property was never assigned via WithCosmosDB().

Solutions

1. Call .WithCosmosDB(cosmosDbBuilder) on the capability host before finalizing
2. Ensure the CosmosDB resource is created (AddAzureCosmosDB) and passed to the capability host
3. Check that no early-return or conditional branch skips the WithCosmosDB call

Example fix

// before
project.AddCapabilityHost("cap").WithStorage(storage).WithSearch(search);

// after
project.AddCapabilityHost("cap").WithCosmosDB(cosmosDb).WithStorage(storage).WithSearch(search);

if (cosmosDb is null)
{
    throw new InvalidOperationException("Capability host requires a CosmosDB resource.");
}
project.AddCapabilityHost(name).WithCosmosDB(cosmosDb);

try { /* finalize capability host / run app host */ }
catch (InvalidOperationException ex) when (ex.Message.Contains("requires a CosmosDB resource"))
{
    // Attach a CosmosDB resource and retry.
}

When it happens

Trigger: Creating a capability host with AddCapabilityHost / withCapabilityHost and finalizing it without calling WithCosmosDB() (or withCapabilityHost equivalent) with a CosmosDB resource.

Common situations: Configuring only Storage or Search and forgetting CosmosDB; conditionally skipping CosmosDB in some environments; a partially migrated capability-host configuration where one With* call was dropped.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Azure Cognitive Services project resource
• Microsoft Foundry project resource
• Model must be a FoundryModel or a string model name.
• Model version and format are required when the model is…
• Model version and format must be omitted when using a…

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/Project/ProjectResource.cs:338

    /// The Storage resource to use for file storage.
    /// </summary>
    public AzureStorageResource? Storage { get; set; }

    /// <summary>
    /// The Azure Search resource to use for vector search capabilities.
    /// </summary>
    public AzureSearchResource? Search { get; set; }

    /// <summary>
    /// An OpenAI-type Microsoft Foundry account to use for AI model calls, if any.
    /// </summary>
    public FoundryResource? AzureOpenAI { get; set; }

    internal void Validate(string projectName)
    {
        if (CosmosDB is null)
        {
            throw new InvalidOperationException($"Capability host '{Name}' on project '{projectName}' requires a CosmosDB resource. Call WithCosmosDB() on the capability host builder.");
        }
        if (Storage is null)
        {
            throw new InvalidOperationException($"Capability host '{Name}' on project '{projectName}' requires a Storage resource. Call WithStorage() on the capability host builder.");
        }
        if (Search is null)
        {
            throw new InvalidOperationException($"Capability host '{Name}' on project '{projectName}' requires a Search resource. Call WithSearch() on the capability host builder.");
        }
    }
}

/// <summary>
/// A fluent builder for configuring a capability host on a Microsoft Foundry project.
/// </summary>
public class CapabilityHostBuilder(IResourceBuilder<AzureCognitiveServicesProjectResource> projectBuilder, CapabilityHostConfiguration configuration)
{
    /// <summary>

View on GitHub (pinned to 25830f84bd)