microsoft/aspire · error · DistributedApplicationException

Foundry hosted agent for target resource

Error message

Foundry hosted agent for target resource '{targetResourceName}' contains environment variable names that are reserved by Foundry Hosted Agents. Reserved name(s): '{string.Join("', '", reservedNames)}'

What it means

Foundry Hosted Agents reserve certain environment variable names for platform use. ValidateEnvironmentVariableNamesAreNotReserved throws this DistributedApplicationException when a user-declared env var collides with a reserved name (checked via IsReservedEnvironmentVariableName); the message lists every reserved name used.

Solutions

Rename the listed environment variables to non-reserved names.
Remove the variables entirely if Foundry already injects them automatically at runtime.
Consult the Foundry Hosted Agents docs for the full reserved-name list before naming env vars.

Example fix

// before
agent.WithEnvironment("AGENT_NAME", value); // reserved

// after
agent.WithEnvironment("CUSTOM_AGENT_NAME", value);

Defensive patterns

Strategy: validation

Validate before calling

// before adding env vars, check each against the reserved list
if (HostedAgentConfiguration.IsReservedEnvironmentVariableName(name))
    throw new InvalidOperationException($"'{name}' is reserved by Foundry Hosted Agents; choose another name.");

Try / catch

try { /* create agent version */ } catch (DistributedApplicationException ex) when (ex.Message.Contains("reserved by Foundry Hosted Agents")) { /* rename variables and retry */ }

Prevention

Prefix user env vars with an app-specific prefix (e.g. MYAPP_) to avoid reserved-name collisions.
Keep the Foundry Hosted Agents reserved-name list handy when naming variables.
Do not attempt to override platform-injected variables.

When it happens

Trigger: Calling ToProjectsAgentVersionCreationOptions when any hosted-agent environment variable name matches a name reserved by Foundry Hosted Agents (e.g. platform-injected names like AGENT_* / FOUNDRY_* style variables).

Common situations: Trying to override a platform variable the agent runtime injects itself; copying local .env files that already use the reserved keys; assuming all env vars are freely nameable like in a plain container.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentConfiguration.cs:195

        throw new DistributedApplicationException(
            $"Foundry hosted agent for target resource '{targetResourceName}' contains environment variable names that are not supported by Foundry Hosted Agents. " +
            $"Environment variable names must contain only ASCII letters, digits, or underscores. " +
            $"Invalid name(s): '{string.Join("', '", invalidNames)}'");
    }

    private static void ValidateEnvironmentVariableNamesAreNotReserved(IEnumerable<string> environmentVariableNames, string? targetResourceName)
    {
        var reservedNames = environmentVariableNames
            .Where(IsReservedEnvironmentVariableName)
            .Order(StringComparer.Ordinal)
            .ToArray();

        if (reservedNames.Length == 0)
        {
            return;
        }

        throw new DistributedApplicationException(
            $"Foundry hosted agent for target resource '{targetResourceName}' contains environment variable names that are reserved by Foundry Hosted Agents. " +
            $"Reserved name(s): '{string.Join("', '", reservedNames)}'");
    }

    internal static bool IsReservedEnvironmentVariableName(string name)
    {
        return string.Equals(name, "PORT", StringComparison.OrdinalIgnoreCase) ||
            name.StartsWith("FOUNDRY_", StringComparison.OrdinalIgnoreCase) ||
            name.StartsWith("AGENT_", StringComparison.OrdinalIgnoreCase);
    }

    // hosted agent environment variables must contain only letters, digits, or underscores.
    [GeneratedRegex("^[A-Za-z0-9_]+$")]
    private static partial Regex EnvironmentVariableNameRegex();
}

View on GitHub (pinned to 25830f84bd)