microsoft/aspire · error · InvalidOperationException

Endpoint ' ' is internal. Foundry hosted agents can only…

Error message

Endpoint '{endpoint.Name}' is internal. Foundry hosted agents can only reference externally exposed endpoints during publish.

What it means

During publish, Aspire resolves environment variables for Azure Foundry hosted agents from endpoint references. Only externally exposed endpoints (or endpoints on the agent's own target resource) may be referenced, because publish bakes concrete URLs into the deployed agent's configuration. ResolvePublishedEndpointAsync throws this when an endpoint reference points at an internal (non-external) endpoint.

Solutions

1. Mark the referenced endpoint external on the owning resource (e.g. .WithExternalHttpEndpoints()).
2. Reference the hosted agent's own target resource endpoints directly if internal access is intended.
3. Bind to the resource's connection string or a different externally-exposed endpoint.
4. If the endpoint must stay internal, use a service-discovery reference rather than a baked endpoint value in the agent environment.

Example fix

// before
builder.AddProject<Projects.Agent>("agent")
    .WithEnvironment("API_URL", api.GetEndpoint("http")); // internal endpoint

// after
var api = builder.AddProject<Projects.Api>("api")
    .WithExternalHttpEndpoints();
builder.AddProject<Projects.Agent>("agent")
    .WithEnvironment("API_URL", api.GetEndpoint("https"));

// Detect internal endpoint references on a hosted agent before publish
foreach (var env in agent.EnvironmentVariables)
{
    if (env.Value is EndpointReference ep &&
        ep.Resource != agent.Target && !ep.EndpointAnnotation.IsExternal)
    {
        throw new InvalidOperationException(
            $"{env.Name} references internal endpoint '{ep.EndpointAnnotation.Name}'. Mark it external before publish.");
}

static bool IsPublishableEndpoint(EndpointReference ep, IResource agentTarget) =>
    ep.Resource == agentTarget || ep.EndpointAnnotation.IsExternal;

When it happens

Trigger: A hosted agent's environment variable is bound via an endpoint reference whose EndpointAnnotation has IsExternal == false and whose resource is not hostedAgent.Target, while running in publish/deploy mode (ResolveValueProviderAsync path).

Common situations: Binding to an internal-only service endpoint and publishing; the referenced project lacks .WithExternalHttpEndpoints(); copy-pasted run-mode binding code applied to a published agent.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Foundry project ' ' did not resolve to an absolute HTTPS…
• Unable to resolve environment variable
• A SearchIndexClient could not be configured. Ensure valid…
• Endpoint ' ' on resource ' ' is not exposed by the Azure…
• Project ' ' does not have a valid endpoint.

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/HostedAgent/AzureHostedAgentResource.cs:469

        }

        return string.Format(CultureInfo.InvariantCulture, expression.Format, args);
    }

    private static async ValueTask<string?> ResolvePublishedEndpointAsync(
        EndpointReferenceExpression endpointReferenceExpression,
        DistributedApplicationExecutionContext context,
        AzureHostedAgentResource hostedAgent,
        IResource resource,
        string environmentVariableName,
        CancellationToken cancellationToken)
    {
        var endpointReference = endpointReferenceExpression.Endpoint;
        var endpoint = endpointReference.EndpointAnnotation;

        if (endpointReference.Resource != hostedAgent.Target && !endpoint.IsExternal)
        {
            throw CreateEndpointResolutionException(hostedAgent, resource, environmentVariableName, endpointReference, $"Endpoint '{endpoint.Name}' is internal. Foundry hosted agents can only reference externally exposed endpoints during publish.");
        }

        if (!ComputeEnvironmentEndpointResolver.TryGetEffectiveComputeEnvironment(endpointReference.Resource, out var computeEnvironment))
        {
            var reason = $"Resource '{endpointReference.Resource.Name}' does not have a compute environment deployment target.";
            throw CreateEndpointResolutionException(hostedAgent, resource, environmentVariableName, endpointReference, reason);
        }

#pragma warning disable ASPIRECOMPUTE002
        var expression = computeEnvironment.GetEndpointPropertyExpression(endpointReferenceExpression);
#pragma warning restore ASPIRECOMPUTE002

        return await expression.GetValueAsync(
            new ValueProviderContext
            {
                ExecutionContext = context,
                Caller = resource
            },

View on GitHub (pinned to 25830f84bd)