{"record":{"id":"ee6404bb6e520c8d","repo":"microsoft/aspire","slug":"azure-ai-search-tool-name-does-not-have-a-backing-resource","errorCode":null,"errorMessage":"Azure AI Search tool '{Name}' does not have a backing resource configured. Call .WithReference(searchResource) to link it to an Azure AI Search resource.","messagePattern":"Azure AI Search tool '(.+?)' does not have a backing resource configured\\. Call \\.WithReference\\(searchResource\\) to link it to an Azure AI Search resource\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Foundry/ToolResources/AzureAISearchToolResource.cs","lineNumber":59,"sourceCode":"\n    /// <summary>\n    /// Gets or sets the optional search index name to query. If not set, the tool\n    /// will use a default or prompt-specified index at runtime.\n    /// </summary>\n    public string? IndexName { get; set; }\n\n    /// <summary>\n    /// Gets or sets the Foundry project connection resource for this search tool.\n    /// Set by <see cref=\"PromptAgentBuilderExtensions.WithReference(IResourceBuilder{AzureAISearchToolResource}, IResourceBuilder{AzureSearchResource})\"/>.\n    /// </summary>\n    internal AzureCognitiveServicesProjectConnectionResource? Connection { get; set; }\n\n    /// <inheritdoc/>\n    public override async Task<ResponseTool> ToAgentToolAsync(CancellationToken cancellationToken = default)\n    {\n        if (Connection is null)\n        {\n            throw new InvalidOperationException(\n                $\"Azure AI Search tool '{Name}' does not have a backing resource configured. \" +\n                \"Call .WithReference(searchResource) to link it to an Azure AI Search resource.\");\n        }\n\n        // The connection ID output is resolved after infrastructure provisioning\n        var connectionIdRef = new BicepOutputReference(\"id\", Connection);\n        var connectionId = await connectionIdRef.GetValueAsync(cancellationToken).ConfigureAwait(false);\n        if (string.IsNullOrEmpty(connectionId))\n        {\n            throw new InvalidOperationException(\n                $\"Failed to resolve connection ID for Azure AI Search tool '{Name}'. \" +\n                \"The Foundry project connection may not have been provisioned correctly.\");\n        }\n\n        var index = new AzureAISearchToolIndex\n        {\n            ProjectConnectionId = connectionId,\n            IndexName = IndexName","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Foundry/ToolResources/AzureAISearchToolResource.cs#L41-L77","documentation":"An Azure AI Search tool used by a Foundry prompt agent must be linked to a backing Azure AI Search resource through WithReference. ToAgentToolAsync throws when the tool's Connection is still null because the connection ID cannot be constructed without a backing resource.","triggerScenarios":"Adding an AI Search tool via AddAISearchTool and passing it to agent.WithTool without ever calling WithReference(searchResource) on the tool builder.","commonSituations":"Skipping the WithReference step when copying minimal samples; conditional wiring that never executes; assuming the tool works standalone without a search resource.","solutions":["Call WithReference(searchResource) on the AI Search tool builder, where searchResource comes from builder.AddAzureSearch(...).","Verify the WithReference call happens before the agent is created/deployed.","Confirm tool.Resource.Connection is set at runtime before deploying."],"exampleFix":"// before\nvar searchTool = project.AddAISearchTool(\"search-tool\");\nagent.WithTool(searchTool);\n// after\nvar searchTool = project.AddAISearchTool(\"search-tool\")\n    .WithReference(search);\nagent.WithTool(searchTool);","handlingStrategy":"validation","validationCode":"if (searchToolBuilder.Resource.Connection is null) throw new InvalidOperationException(\"Call WithReference(searchResource) before adding the tool to an agent.\");","typeGuard":"bool isLinked(AzureAISearchToolResource t) => t.Connection is not null;","tryCatchPattern":null,"preventionTips":["Always chain WithReference(search) immediately after AddAISearchTool.","Assert tool.Connection is set in AppHost model tests.","Never add unconfigured tools to agents."],"tags":["azure","foundry","ai-search","missing-configuration","tool"],"backgroundTag":"missing-required-config","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}