microsoft/aspire · error · InvalidOperationException

Endpoint ' ' on resource ' ' is not exposed by the Azure…

Error message

Endpoint '{endpointName}' on resource '{resource.TargetResource.Name}' is not exposed by the Azure sandbox deployment target. Configure it as an external HTTP endpoint before referencing its sandbox URL.

What it means

Thrown by ResolveSandboxEndpoint when no endpoint on the sandbox container resource matches the requested name (or falls back to target-port matching) among the endpoints exposed by the Azure sandbox deployment target. The caller is told to mark the endpoint as an external HTTP endpoint so the sandbox will expose and persist a URL for it.

Solutions

Mark the endpoint as an external HTTP endpoint (e.g. .WithHttpEndpoint(..., isExternal: true)) before referencing its sandbox URL.
Double-check the endpoint name string matches the declaration exactly (case-sensitive).
Redeploy the sandbox so the newly exposed endpoint is persisted in the deployment state Ports section.
Confirm the consuming reference targets the same resource the endpoint was declared on.

Example fix

// before
.WithHttpEndpoint(targetPort: 8080, name: "http")
// after
.WithHttpEndpoint(targetPort: 8080, name: "http", isExternal: true);

Defensive patterns

Strategy: validation

Validate before calling

bool EndpointExists(IResource r, string name) =>
    r.ResolveEndpoints().Any(e => string.Equals(e.EndpointName, name, StringComparison.Ordinal));

Try / catch

try { var url = await provider.GetValueAsync(); }
catch (InvalidOperationException ex) { logger.LogError(ex, "Unknown or unexposed endpoint '{Name}'", name); throw; }

Prevention

Use constants for endpoint names to avoid typos.
Configure endpoints with isExternal: true before consumers reference their URLs.
Re-run deployment whenever endpoint declarations change.

When it happens

Trigger: Resolving a sandbox endpoint for endpointName where resource.TargetResource.ResolveEndpoints() contains no external HTTP endpoint with that name (and no endpoint sharing the target port as a fallback).

Common situations: Endpoint declared without isExternal/external HTTP semantics; misspelled endpoint name; the endpoint was added to the resource after the sandbox deployment state was generated.

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

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure.Sandboxes/AzureSandboxEndpointPropertyValueProvider.cs:184

        {
            if (resolvedTargetPort is int targetPort &&
                endpoint.TargetPort == targetPort)
            {
                fallbackEndpoint ??= endpoint;
            }

            if (string.Equals(endpoint.Name, endpointName, StringComparison.Ordinal))
            {
                return endpoint;
            }
        }

        if (fallbackEndpoint is { } matchedEndpoint)
        {
            return matchedEndpoint;
        }

        throw new InvalidOperationException($"Endpoint '{endpointName}' on resource '{resource.TargetResource.Name}' is not exposed by the Azure sandbox deployment target. Configure it as an external HTTP endpoint before referencing its sandbox URL.");
    }

    private static int? ResolveEndpointTargetPort(AzureSandboxContainerResource resource, string endpointName)
    {
        foreach (var resolvedEndpoint in resource.TargetResource.ResolveEndpoints())
        {
            if (string.Equals(resolvedEndpoint.Endpoint.Name, endpointName, StringComparison.Ordinal))
            {
                return AzureSandboxContainerDeployment.ResolveSandboxTargetPort(resource.TargetResource, resolvedEndpoint);
            }
        }

        return null;
    }
}

View on GitHub (pinned to 25830f84bd)