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

FoundryToolboxAzureAISearchToolDefinition.ResolveAsync reads the 'id' Bicep output of the Foundry project connection resource to populate AzureAISearchToolIndex.ProjectConnectionId. That output only exists after Azure provisioning; if it is empty at resolve time, the tool cannot reference the connection, so this InvalidOperationException is thrown (mirroring AzureAISearchToolResource behavior).

Solutions

1. Deploy/provision the AppHost (azd provision or publish/deploy) so the connection's 'id' Bicep output is populated, then resolve the tool.
2. Verify the AzureCognitiveServicesProjectConnectionResource passed to the tool actually deployed successfully (check deployment logs/portal).
3. Only run this code path in deploy/publish mode, or guard it so it is not exercised in local run mode.
4. Catch InvalidOperationException and check whether the BicepOutputReference("id", Connection) has a value before proceeding.

Example fix

// before
if (!app.Environment.IsPublishMode()) { ResolveToolbox(); }
// after
if (app.Environment.IsPublishMode()) { ResolveToolbox(); } // connection id exists only after provisioning

var idRef = new BicepOutputReference("id", connection);
var id = await idRef.GetValueAsync(ct);
if (string.IsNullOrEmpty(id)) throw new InvalidOperationException("Connection id not provisioned yet.");

static bool ConnectionProvisioned(AzureCognitiveServicesProjectConnectionResource c) =>
    !string.IsNullOrEmpty(new BicepOutputReference("id", c).Value);

try { await definition.ResolveAsync(ct); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Failed to resolve connection ID"))
{ logger.LogError(ex, "Run azd provision/deploy so the Foundry project connection 'id' output exists."); }

When it happens

Trigger: Resolving the toolbox tool in AppHost (run) mode before `azd provision`/deployment has produced the connection's 'id' output; the connection resource failed or was skipped during provisioning; the wrong connection resource was wired into the tool.

Common situations: Running F5 in AppHost mode where Bicep outputs aren't materialized; a deployment that partially failed leaving the project connection unprovisioned; renaming/recreating the Foundry project connection so the cached output is missing.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Failed to resolve connection ID for Azure AI Search tool
• A of type cannot be assigned to a BicepValue< >.
• An Azure principal parameter was not supplied a value…
• Azure AI Search tool
• Azure AI Search tool

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxToolDefinition.cs:391

    /// </summary>
    public AzureCognitiveServicesProjectConnectionResource Connection { get; }

    /// <summary>
    /// Gets the Azure AI Search index name.
    /// </summary>
    public string IndexName { get; }

    public string? Description { get; }

    internal override async ValueTask<ResolvedFoundryToolboxTool> ResolveAsync(CancellationToken cancellationToken)
    {
        // The Foundry project connection's "id" bicep output is only populated after provisioning,
        // so this resolves to a real value only at deploy time. Matches AzureAISearchToolResource.
        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]);
        var unnamedTool = new AzureAISearchTool(options);
        var unnamedJson = ModelReaderWriter.Write(
            unnamedTool,
            ModelReaderWriterOptions.Json,
            AzureAIProjectsAgentsContext.Default);
        using var unnamedDocument = JsonDocument.Parse(unnamedJson);
        using var stream = new MemoryStream();
        using (var writer = new Utf8JsonWriter(stream))

View on GitHub (pinned to 25830f84bd)