microsoft/aspire · error · InvalidOperationException

Azure AI Search tool

Error message

Azure AI Search tool '{tool.Resource.Name}' already has a backing resource configured.

What it means

An Azure AI Search tool in a Foundry prompt agent can have exactly one backing resource/connection. WithReference throws when the tool's Connection is already set, preventing a second WithReference call from silently overwriting the backing search resource.

Solutions

1. Remove the duplicate WithReference call so the search tool is backed by exactly one Azure AI Search resource.
2. If you intend to change the backing resource, recreate the tool with the desired resource instead of re-wiring.
3. Guard conditional wiring so it executes only once per tool.

Example fix

// before
searchTool.WithReference(searchA);
searchTool.WithReference(searchB);
// after
searchTool.WithReference(searchB);

if (searchToolBuilder.Resource.Connection is not null) { /* already configured; skip or throw */ }

bool isUnconfigured(FoundryToolResource t) => t.Connection is null;

When it happens

Trigger: Calling WithReference(search) twice on the same Azure AI Search tool builder, or calling it after another overload already assigned tool.Resource.Connection.

Common situations: Merging sample code that wires the same tool twice; conditional wiring that can run more than once; copying WithReference lines from another tool builder onto an already-configured tool.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Azure AI Search tool
• Bing Grounding tool ' ' already has a connection configured.
• Bing Grounding tool ' ' does not have a project connection…
• Failed to resolve connection ID for Azure AI Search tool
• Failed to resolve connection ID for Azure AI Search tool

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/PromptAgent/PromptAgentBuilderExtensions.cs:338

    /// Links an Azure AI Search tool to a backing <see cref="AzureSearchResource"/>,
    /// creating the necessary Foundry project connection and role assignments.
    /// </summary>
    /// <ats-summary>Links an Azure AI Search tool to a backing search resource.</ats-summary>
    /// <param name="tool">The Azure AI Search tool resource builder.</param>
    /// <param name="search">The Azure AI Search resource to use for grounding.</param>
    /// <returns>A reference to the <see cref="IResourceBuilder{T}"/> for chaining.</returns>
    /// <ats-returns>The resource builder.</ats-returns>
    [AspireExport]
    public static IResourceBuilder<AzureAISearchToolResource> WithReference(
        this IResourceBuilder<AzureAISearchToolResource> tool,
        IResourceBuilder<AzureSearchResource> search)
    {
        ArgumentNullException.ThrowIfNull(tool);
        ArgumentNullException.ThrowIfNull(search);

        if (tool.Resource.Connection is not null)
        {
            throw new InvalidOperationException(
                $"Azure AI Search tool '{tool.Resource.Name}' already has a backing resource configured.");
        }

        // Find the project builder to create the connection
        var projectBuilder = tool.ApplicationBuilder.CreateResourceBuilder(tool.Resource.Project);

        // AddConnection(IResourceBuilder<AzureSearchResource>) already handles role assignments
        var connection = projectBuilder.AddConnection(search);

        tool.Resource.Connection = connection.Resource;
        tool.Resource.SearchResource = search.Resource;
        return tool;
    }

    /// <summary>
    /// Adds a Bing Grounding tool to a Microsoft Foundry project, enabling agents to
    /// ground their responses using Bing Search results.
    /// </summary>

View on GitHub (pinned to 25830f84bd)