microsoft/aspire · error · ArgumentException

The Foundry Local endpoint must be an absolute HTTP or…

Error message

The Foundry Local endpoint must be an absolute HTTP or HTTPS URL.

What it means

RunAsFoundryLocal configures a Foundry resource to run against a local Foundry Local service. If an explicit endpoint string is supplied, it must parse as an absolute URI with scheme http or https; anything else (relative URL, missing scheme, wrong scheme like ftp or ws) throws this ArgumentException.

Solutions

Prefix the endpoint with http:// or https:// and ensure it is fully qualified
Validate with Uri.TryCreate(uriString, UriKind.Absolute, out var u) and u.Scheme is "http" or "https" before passing
Fix the environment/config value supplying the endpoint

Example fix

// before
.RunAsFoundryLocal(endpoint: "localhost:5100");
// after
.RunAsFoundryLocal(endpoint: "http://localhost:5100");

Defensive patterns

Strategy: validation

Validate before calling

bool IsValidEndpoint(string? e) =>
    Uri.TryCreate(e, UriKind.Absolute, out var u) && u.Scheme is "http" or "https";

Try / catch

try { foundry.RunAsFoundryLocal(endpoint); }
catch (ArgumentException ex) when (ex.Message.Contains("absolute HTTP or HTTPS")) { /* fix the URL */ }

Prevention

Always store Foundry Local endpoints as fully qualified absolute URLs with scheme
Validate config-sourced URLs with Uri.TryCreate(UriKind.Absolute) before passing
Watch for env-var values that omit the scheme

When it happens

Trigger: builder.AddFoundry(...).RunAsFoundryLocal(endpoint: "localhost:8080") or endpoint: "ftp://host" — a string that is not an absolute http/https URL.

Common situations: Forgetting the http:// scheme prefix; using a ws:// or https-rel path; environment variable containing a malformed URL; trailing config typos.

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/d14d991f7185dd60. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/FoundryExtensions.cs:215

    [AspireExport]
    public static IResourceBuilder<FoundryResource> RunAsFoundryLocal(
        this IResourceBuilder<FoundryResource> builder,
        string? endpoint = null)
    {
        ArgumentNullException.ThrowIfNull(builder);

        if (builder.ApplicationBuilder.ExecutionContext.IsPublishMode)
        {
            return builder;
        }

        Uri? existingEndpoint = null;
        if (endpoint is not null)
        {
            if (!Uri.TryCreate(endpoint, UriKind.Absolute, out existingEndpoint) ||
                existingEndpoint.Scheme is not ("http" or "https"))
            {
                throw new ArgumentException("The Foundry Local endpoint must be an absolute HTTP or HTTPS URL.", nameof(endpoint));
            }

            existingEndpoint = EnsureTrailingSlash(existingEndpoint);
        }

        var resource = builder.Resource;
        ThrowIfProjectsConfiguredForLocal(builder, resource);
        resource.Annotations.Add(new EmulatorResourceAnnotation());
        resource.ApiKey = FoundryLocalService.ApiKey;
        resource.EmulatorServiceUri = existingEndpoint;
        resource.ManageLocalService = existingEndpoint is null;

        builder.WithInitializer();
        if (resource.ManageLocalService)
        {
            builder.OnResourceStopped(static (_, _, ct) => FoundryLocalService.StopAsync(ct));
            builder.ApplicationBuilder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IHostedService, FoundryLocalLifecycleService>());
        }

View on GitHub (pinned to 25830f84bd)