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 not supported by Foundry Hosted Agents. Environment variable names must contain only ASCII letters, digits, or underscores. Invalid name(s): '{string.Join("', '", invalidNames)}'

What it means

Foundry Hosted Agents only accept environment variable names made of ASCII letters, digits, and underscores. ValidateEnvironmentVariableNames throws this DistributedApplicationException when any environment variable name on the hosted agent contains other characters (hyphens, dots, spaces, leading digits are fine only if ASCII alnum/underscore per the rule).

Solutions

Rename the listed environment variables to contain only A-Z, a-z, 0-9, and underscore (e.g. "my-var" -> "MY_VAR").
Sanitize names programmatically: replace non-[A-Za-z0-9_] characters with '_' before calling WithEnvironment.
Check for framework-added environment variables with invalid names and remove or rename them.

Example fix

// before
agent.WithEnvironment("my-setting", value);

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

Defensive patterns

Strategy: validation

Validate before calling

static bool IsValidEnvName(string name) =>
    name.Length > 0 && name.All(c => c is >= 'a' and <= 'z' or >= 'A' and <= 'Z' or >= '0' and <= '9' or '_');
// validate all env var names before creating the agent version

Try / catch

try { /* ToProjectsAgentVersionCreationOptions */ } catch (DistributedApplicationException ex) when (ex.Message.Contains("not supported by Foundry Hosted Agents")) { /* sanitize names and retry */ }

Prevention

Sanitize environment variable names with a helper that replaces non-[A-Za-z0-9_] characters with '_' before WithEnvironment.
Avoid deriving env names directly from kebab-case service names.
Add an early validation step in the app model for all hosted-agent env var names.

When it happens

Trigger: Calling ToProjectsAgentVersionCreationOptions when any env var added to the hosted agent (via WithEnvironment or resource environment) fails the ASCII letter/digit/underscore check; the message lists each invalid name.

Common situations: Using kebab-case names like "my-var" or dotted names like "My.Config" copied from other clouds; deriving env var names from service names that contain hyphens; mistakenly using environment-variable *values* instead of names.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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

Appendix: source

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

        if (ProtocolVersions.Count == 0)
        {
            throw new DistributedApplicationException($"Foundry hosted agent for target resource '{targetResourceName}' must declare at least one protocol version.");
        }
    }

    private static void ValidateEnvironmentVariableNames(IEnumerable<string> environmentVariableNames, string? targetResourceName)
    {
        var invalidNames = environmentVariableNames
            .Where(static name => !EnvironmentVariableNameRegex().IsMatch(name))
            .Order(StringComparer.Ordinal)
            .ToArray();

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

        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(

View on GitHub (pinned to 25830f84bd)