microsoft/aspire · error · InvalidOperationException

Unable to resolve environment variable

Error message

Unable to resolve environment variable '{environmentVariableName}' for Foundry hosted agent '{hostedAgent.Name}' from target resource '{resource.Name}'. Endpoint '{endpointReference.EndpointName}' on resource '{endpointReference.Resource.Name}' cannot be used. Resource '{endpointReference.Resource.Name}' does not have a compute environment deployment target.

What it means

When publishing a Foundry hosted agent, each endpoint-referenced environment variable must resolve to a resource that has a compute environment deployment target, so Aspire can compute the published endpoint URL. This error means the referenced resource is not deployed into any compute environment, so the agent's environment variable cannot be resolved.

Solutions

Add the referenced resource to a compute environment so it has a deployment target.
Reference a resource actually deployed into the same compute environment as the agent.
If the value is not a deployed endpoint, bind via a connection string or explicit URL instead.
Verify the endpoint's resource is associated with the compute environment before publish.

Example fix

// before
var agent = builder.AddProject<Projects.Agent>("agent")
    .WithEnvironment("API_URL", externalApi.GetEndpoint("https")); // not in compute env

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

Defensive patterns

Strategy: validation

Validate before calling

// Only reference endpoints of resources deployed into a compute environment
if (!IsDeployedInComputeEnvironment(endpointRef.Resource))
    throw new InvalidOperationException(
        $"Resource '{endpointRef.Resource.Name}' has no compute environment; add it before publishing the agent.");

Prevention

Add every endpoint-referenced project to the compute environment (e.g. env.AddProject(...)).
Reference connection strings or explicit URLs for resources that are not deployed endpoints.
Run a publish dry-run locally to catch unresolved environment variables before CI deploy.

When it happens

Trigger: ResolvePublishedEndpointAsync calls ComputeEnvironmentEndpointResolver.TryGetEffectiveComputeEnvironment(endpointReference.Resource, ...) which returns false, causing CreateEndpointResolutionException during publish of the agent's environment variable.

Common situations: Referencing an endpoint of a resource that isn't deployed (local-only project, container, external process); forgetting to add the referenced project to the compute environment; referencing infrastructure resources via endpoint bindings.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

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

        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
            },
            cancellationToken).ConfigureAwait(false);
    }

    private static InvalidOperationException CreateEndpointResolutionException(
        AzureHostedAgentResource hostedAgent,
        IResource resource,

View on GitHub (pinned to 25830f84bd)