{"record":{"id":"f27b52013fc29446","repo":"microsoft/aspire","slug":"foundry-hosted-agent-for-target-resource-targetresourcename-f27b52","errorCode":null,"errorMessage":"Foundry hosted agent for target resource '{targetResourceName}' contains environment variable names that are reserved by Foundry Hosted Agents. Reserved name(s): '{string.Join(\"', '\", reservedNames)}'","messagePattern":"Foundry hosted agent for target resource '(.+?)' contains environment variable names that are reserved by Foundry Hosted Agents\\. Reserved name\\(s\\): '(.+?)'","errorType":"validation","errorClass":"DistributedApplicationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentConfiguration.cs","lineNumber":195,"sourceCode":"        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(\n            $\"Foundry hosted agent for target resource '{targetResourceName}' contains environment variable names that are reserved by Foundry Hosted Agents. \" +\n            $\"Reserved name(s): '{string.Join(\"', '\", reservedNames)}'\");\n    }\n\n    internal static bool IsReservedEnvironmentVariableName(string name)\n    {\n        return string.Equals(name, \"PORT\", StringComparison.OrdinalIgnoreCase) ||\n            name.StartsWith(\"FOUNDRY_\", StringComparison.OrdinalIgnoreCase) ||\n            name.StartsWith(\"AGENT_\", StringComparison.OrdinalIgnoreCase);\n    }\n\n    // hosted agent environment variables must contain only letters, digits, or underscores.\n    [GeneratedRegex(\"^[A-Za-z0-9_]+$\")]\n    private static partial Regex EnvironmentVariableNameRegex();\n}\n","sourceCodeStart":177,"sourceCodeEnd":211,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentConfiguration.cs#L177-L211","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\nagent.WithEnvironment(\"AGENT_NAME\", value); // reserved\n\n// after\nagent.WithEnvironment(\"CUSTOM_AGENT_NAME\", value);","handlingStrategy":"validation","validationCode":"// before adding env vars, check each against the reserved list\nif (HostedAgentConfiguration.IsReservedEnvironmentVariableName(name))\n    throw new InvalidOperationException($\"'{name}' is reserved by Foundry Hosted Agents; choose another name.\");","typeGuard":null,"tryCatchPattern":"try { /* create agent version */ } catch (DistributedApplicationException ex) when (ex.Message.Contains(\"reserved by Foundry Hosted Agents\")) { /* rename variables and retry */ }","preventionTips":["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."],"tags":["azure-ai-foundry","aspire-hosting","environment-variables","reserved-names"],"backgroundTag":"invalid-config-value","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"}