microsoft/aspire · error · InvalidOperationException

Failed to resolve connection ID for Azure AI Search tool

Error message

Failed to resolve connection ID for Azure AI Search tool '{Name}'. The Foundry project connection may not have been provisioned correctly.

What it means

The AI Search tool resolves its connection ID from the backing connection's 'id' Bicep output, which only exists after infrastructure provisioning succeeds. An empty result means the Foundry project connection was not provisioned (or produced no id output), so the agent tool cannot reference it.

Solutions

  1. Re-run the Azure provisioning step (aspire publish/deploy or azd provision) and confirm it completes without errors.
  2. Inspect the deployed Foundry project connections in the Azure portal to confirm the connection exists.
  3. Check the bicep/infrastructure output names ('id') match what the connection resource emits.
  4. If repeated, delete and re-create the Foundry project connection resources to clear stuck state.
Defensive patterns

Strategy: retry

Validate before calling

var id = await connectionResource.WaitUntilHealthyAsync()?.GetValueAsync(ct); if (string.IsNullOrEmpty(id)) { /* provisioning incomplete; retry or fail fast */ }

Try / catch

try
{
    await agent.DeployAsync(ct);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("Failed to resolve connection ID"))
{
    logger.LogError(ex, "Search connection not provisioned; re-run provisioning.");
    throw;
}

Prevention

When it happens

Trigger: ToAgentToolAsync runs during deployment, BicepOutputReference.GetValueAsync for output 'id' returns null/empty — typically because provisioning failed, the connection resource was not deployed, or the output name changed.

Common situations: Partial Azure deployments; azd provision failures earlier in the pipeline; using the tool locally before any deployment; Azure resource quota or region issues preventing the connection from being created.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/ToolResources/AzureAISearchToolResource.cs:69

    /// </summary>
    internal AzureCognitiveServicesProjectConnectionResource? Connection { get; set; }

    /// <inheritdoc/>
    public override async Task<ResponseTool> ToAgentToolAsync(CancellationToken cancellationToken = default)
    {
        if (Connection is null)
        {
            throw new InvalidOperationException(
                $"Azure AI Search tool '{Name}' does not have a backing resource configured. " +
                "Call .WithReference(searchResource) to link it to an Azure AI Search resource.");
        }

        // The connection ID output is resolved after infrastructure provisioning
        var connectionIdRef = new BicepOutputReference("id", Connection);
        var connectionId = await connectionIdRef.GetValueAsync(cancellationToken).ConfigureAwait(false);
        if (string.IsNullOrEmpty(connectionId))
        {
            throw new InvalidOperationException(
                $"Failed to resolve connection ID for Azure AI Search tool '{Name}'. " +
                "The Foundry project connection may not have been provisioned correctly.");
        }

        var index = new AzureAISearchToolIndex
        {
            ProjectConnectionId = connectionId,
            IndexName = IndexName
        };
        var options = new AzureAISearchToolOptions([index]);
        return new AzureAISearchTool(options);
    }
}

View on GitHub (pinned to 25830f84bd)