{"record":{"id":"e218229b82debe07","repo":"microsoft/aspire","slug":"foundry-hosted-agent-for-target-resource-targetresourcename-e21822","errorCode":null,"errorMessage":"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)}'","messagePattern":"Foundry hosted agent for target resource '(.+?)' 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\\): '(.+?)'","errorType":"validation","errorClass":"DistributedApplicationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentConfiguration.cs","lineNumber":177,"sourceCode":"        if (ProtocolVersions.Count == 0)\n        {\n            throw new DistributedApplicationException($\"Foundry hosted agent for target resource '{targetResourceName}' must declare at least one protocol version.\");\n        }\n    }\n\n    private static void ValidateEnvironmentVariableNames(IEnumerable<string> environmentVariableNames, string? targetResourceName)\n    {\n        var invalidNames = environmentVariableNames\n            .Where(static name => !EnvironmentVariableNameRegex().IsMatch(name))\n            .Order(StringComparer.Ordinal)\n            .ToArray();\n\n        if (invalidNames.Length == 0)\n        {\n            return;\n        }\n\n        throw new DistributedApplicationException(\n            $\"Foundry hosted agent for target resource '{targetResourceName}' contains environment variable names that are not supported by Foundry Hosted Agents. \" +\n            $\"Environment variable names must contain only ASCII letters, digits, or underscores. \" +\n            $\"Invalid name(s): '{string.Join(\"', '\", invalidNames)}'\");\n    }\n\n    private static void ValidateEnvironmentVariableNamesAreNotReserved(IEnumerable<string> environmentVariableNames, string? targetResourceName)\n    {\n        var reservedNames = environmentVariableNames\n            .Where(IsReservedEnvironmentVariableName)\n            .Order(StringComparer.Ordinal)\n            .ToArray();\n\n        if (reservedNames.Length == 0)\n        {\n            return;\n        }\n\n        throw new DistributedApplicationException(","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentConfiguration.cs#L159-L195","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nagent.WithEnvironment(\"my-setting\", value);\n\n// after\nagent.WithEnvironment(\"MY_SETTING\", value);","handlingStrategy":"validation","validationCode":"static bool IsValidEnvName(string name) =>\n    name.Length > 0 && name.All(c => c is >= 'a' and <= 'z' or >= 'A' and <= 'Z' or >= '0' and <= '9' or '_');\n// validate all env var names before creating the agent version","typeGuard":null,"tryCatchPattern":"try { /* ToProjectsAgentVersionCreationOptions */ } catch (DistributedApplicationException ex) when (ex.Message.Contains(\"not supported by Foundry Hosted Agents\")) { /* sanitize names and retry */ }","preventionTips":["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."],"tags":["azure-ai-foundry","aspire-hosting","environment-variables","validation"],"backgroundTag":"invalid-identifier-format","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}