microsoft/aspire · error · InvalidOperationException

Toolbox ' ' did not resolve to an absolute HTTPS endpoint.

Error message

Toolbox '{Name}' did not resolve to an absolute HTTPS endpoint.

What it means

During run-mode deployment verification, WaitForToolDiscoveryAsync resolves the toolbox version's URI expression and requires an absolute HTTPS URL to call the tool-discovery API. If the resolved endpoint value is null, relative, or non-https, discovery cannot proceed and it throws.

Solutions

Ensure the Foundry project/endpoint is an absolute HTTPS URL so the derived toolbox URI is https.
Confirm the deployment step that produces the toolbox version URI completed successfully before run mode.
Inspect the resolved endpoint expression value in the dashboard/logs and correct the source endpoint.
If using a local emulator, expose it over https or target the real Foundry service.

Example fix

// before
.WithEndpoint(new EndpointReference(emu, "http")); // produces http:// toolbox URI
// after
.WithEndpoint(new EndpointReference(emu, "https")); // absolute https toolbox URI

Defensive patterns

Strategy: validation

Validate before calling

var v = await versionUriExpression.GetValueAsync(ct);
if (!Uri.TryCreate(v, UriKind.Absolute, out var uri) || uri.Scheme != "https") throw new InvalidOperationException($"Toolbox endpoint must be absolute HTTPS, got: {v}");

Type guard

static bool IsAbsoluteHttps(string? value) => Uri.TryCreate(value, UriKind.Absolute, out var u) && u.Scheme == Uri.UriSchemeHttps;

Try / catch

catch (InvalidOperationException ex) when (ex.Message.Contains("did not resolve to an absolute HTTPS endpoint")) { /* inspect the resolved version URI and fix the source endpoint */ }

Prevention

Keep the upstream Foundry project endpoint https so derived toolbox URIs inherit the right scheme.
Ensure the deploy step that emits the toolbox version URI completes before run-mode verification.
Log resolved endpoint expressions when debugging run mode.

When it happens

Trigger: DeployForRunModeAsync waiting for tool discovery when GetVersionUriExpression(...).GetValueAsync returns a value that fails Uri.TryCreate with UriKind.Absolute or whose scheme is not https — typically because the toolbox endpoint output hasn't been produced or points at an http address.

Common situations: The Foundry project endpoint misconfigured (http instead of https) so the derived toolbox URI inherits the wrong scheme; deployment outputs not yet propagated when run-mode verification starts; a proxy/emulator URL that is not absolute https.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/Toolbox/FoundryToolboxResource.cs:421

            await notificationService.PublishUpdateAsync(this, snapshot => snapshot with
            {
                State = new(KnownResourceStates.FailedToStart, KnownResourceStateStyles.Error)
            }).ConfigureAwait(false);
        }
    }

    private async Task WaitForToolDiscoveryAsync(
        PipelineStepContext context,
        string reconciledVersion,
        CancellationToken cancellationToken)
    {
        var endpointValue = await GetVersionUriExpression(reconciledVersion)
            .GetValueAsync(cancellationToken).ConfigureAwait(false);
        if (!Uri.TryCreate(endpointValue, UriKind.Absolute, out var endpoint) ||
            endpoint.Scheme != Uri.UriSchemeHttps)
        {
            throw new InvalidOperationException(
                $"Toolbox '{Name}' did not resolve to an absolute HTTPS endpoint.");
        }

        var credential = context.Services.GetRequiredService<ITokenCredentialProvider>().TokenCredential;
        var accessToken = await credential.GetTokenAsync(
            new TokenRequestContext([AuthorizationScopeValue]),
            cancellationToken).ConfigureAwait(false);
        var requiredToolNames = _tools
            .Where(tool => tool is not FoundryToolboxMcpToolDefinition)
            .Select(tool => tool.Name)
            .ToArray();
        var requiredMcpServerLabels = _tools
            .OfType<FoundryToolboxMcpToolDefinition>()
            .Select(tool => tool.ServerLabel)
            .ToArray();
        var client = context.Services.GetRequiredService<IHttpClientFactory>().CreateClient();
        await new FoundryToolboxReadinessProbe(client).WaitForToolsAsync(
            endpoint,

View on GitHub (pinned to 25830f84bd)