microsoft/aspire · error · ArgumentException

Resource must be a supported capability host resource.

Error message

Resource must be a supported capability host resource.

What it means

WithCapabilityHost only accepts CosmosDB, Storage, Search, or Foundry (Azure OpenAI) resource builders as the capability-host backing resource. Any other resource type falls through the switch and throws this ArgumentException naming the offending parameter.

Solutions

1. Pass one of the supported resource builders: AzureCosmosDBResource, AzureStorageResource, AzureSearchResource, or FoundryResource
2. Check which WithCapabilityHost overload you are calling; ensure the project builder is the 'this' receiver, not passed as the resource argument
3. Add the required Azure resource (e.g. AddAzureSearch) and pass its builder instead

Example fix

// before
project.WithCapabilityHost(cosmosDb, storage, search, redisBuilder);

// after
project.WithCapabilityHost(cosmosDb, storage, search, foundryBuilder);

bool isSupported = resource is IResourceBuilder<AzureCosmosDBResource>
    or IResourceBuilder<AzureStorageResource>
    or IResourceBuilder<AzureSearchResource>
    or IResourceBuilder<FoundryResource>;

static bool IsCapabilityHostResource(IResourceBuilder<IResource> r) =>
    r is IResourceBuilder<AzureCosmosDBResource>
    or IResourceBuilder<AzureStorageResource>
    or IResourceBuilder<AzureSearchResource>
    or IResourceBuilder<FoundryResource>;

try { project.WithCapabilityHost(resource, ...); }
catch (ArgumentException ex) when (ex.ParamName == "resource")
{
    // Unsupported resource type; map or reject it.
}

When it happens

Trigger: Passing e.g. an IResourceBuilder<RedisCacheResource>, a SQL resource, or any non-supported Azure resource to the withCapabilityHost polyglot overload / WithCapabilityHost switch in ProjectBuilderExtension.cs.

Common situations: Using the wrong overload of WithCapabilityHost so the resource argument is interpreted as the backing resource instead of the project; passing a generic container resource expecting it to be wired up automatically.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• Model must be a FoundryModel or a string model name.
• Azure Cognitive Services project resource
• Capability host ' ' on project ' ' requires a CosmosDB…
• Microsoft Foundry project resource
• Model version and format are required when the model is…

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

Appendix: source

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

    [AspireExport]
    internal static IResourceBuilder<AzureCognitiveServicesProjectResource> WithCapabilityHost(
        this IResourceBuilder<AzureCognitiveServicesProjectResource> builder,
        [AspireUnion(
            typeof(IResourceBuilder<AzureCosmosDBResource>),
            typeof(IResourceBuilder<AzureStorageResource>),
            typeof(IResourceBuilder<AzureSearchResource>),
            typeof(IResourceBuilder<FoundryResource>))] object resource)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(resource);

        return resource switch
        {
            IResourceBuilder<AzureCosmosDBResource> cosmosDb => builder.WithCapabilityHostCosmosDB(cosmosDb),
            IResourceBuilder<AzureStorageResource> storage => builder.WithCapabilityHostStorage(storage),
            IResourceBuilder<AzureSearchResource> search => builder.WithCapabilityHostSearch(search),
            IResourceBuilder<FoundryResource> openAI => builder.WithCapabilityHostAzureOpenAI(openAI),
            _ => throw new ArgumentException("Resource must be a supported capability host resource.", nameof(resource))
        };
    }

    /// <summary>
    /// Adds a model deployment to the parent Microsoft Foundry resource of the Microsoft Foundry project.
    /// </summary>
    /// <param name="builder">Aspire resource builder for a project</param>
    /// <param name="name">Name to give the model deployment</param>
    /// <param name="model">The <see cref="FoundryModel"/> to deploy.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/> for the deployment resource.</returns>
    [AspireExportIgnore(Reason = "Polyglot AppHosts use the internal addModelDeployment dispatcher export.")]
    public static IResourceBuilder<FoundryDeploymentResource> AddModelDeployment(
        this IResourceBuilder<AzureCognitiveServicesProjectResource> builder,
        [ResourceName] string name,
        FoundryModel model)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentException.ThrowIfNullOrEmpty(name);

View on GitHub (pinned to 25830f84bd)