{"record":{"id":"ea0ab369a3839926","repo":"microsoft/aspire","slug":"process-command-environment-variable-name-requires-a-value","errorCode":null,"errorMessage":"Process command environment variable '{name}' requires a value.","messagePattern":"Process command environment variable '(.+?)' requires a value\\.","errorType":"exception","errorClass":"DistributedApplicationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/ResourceBuilderExtensions.cs","lineNumber":3411,"sourceCode":"\n    private static Dictionary<string, string> CreateEnvironmentVariables(IReadOnlyDictionary<string, string>? environmentVariables)\n    {\n        var result = new Dictionary<string, string>(StringComparer.Ordinal);\n        if (environmentVariables is null)\n        {\n            return result;\n        }\n\n        foreach (var (name, value) in environmentVariables)\n        {\n            if (string.IsNullOrWhiteSpace(name))\n            {\n                throw new DistributedApplicationException(\"Process command environment variables require non-empty names.\");\n            }\n\n            if (value is null)\n            {\n                throw new DistributedApplicationException($\"Process command environment variable '{name}' requires a value.\");\n            }\n\n            result.Add(name, value);\n        }\n\n        return result;\n    }\n\n    private static ProcessSpec CreateProcessSpec(ExecuteCommandContext context, ProcessCommandSpec processCommandSpec, ProcessCommandOptions commandOptions)\n    {\n        var arguments = processCommandSpec.Arguments ?? [];\n        foreach (var argument in arguments)\n        {\n            if (argument is null)\n            {\n                throw new DistributedApplicationException($\"Process command '{processCommandSpec.ExecutablePath}' arguments cannot contain null values.\");\n            }\n        }","sourceCodeStart":3393,"sourceCodeEnd":3429,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3393-L3429","documentation":"CreateEnvironmentVariables also requires every environment variable to have a non-null value. Because the dictionary type is Dictionary<string, string> yet nulls can appear via polyglot deserialization or null-forgiving casts, the library throws this DistributedApplicationException naming the offending variable.","triggerScenarios":"Pass EnvironmentVariables containing a key whose value is null in withProcessCommand export options or in the ProcessCommandSpecExportData from a createProcessSpec callback, then execute the command.","commonSituations":"Optional env values where 'not set' is represented as null instead of being omitted; JSON deserialization mapping absent fields to null values; dictionaries built from object graphs where a property is null.","solutions":["Omit entries with null values instead of adding them to the dictionary.","Substitute an empty string ('') when a variable must exist but has no value.","Validate values before building the dictionary and throw early with context."],"exampleFix":"// before\nenv[\"API_KEY\"] = config[\"ApiKey\"]; // null when not configured\n// after\nif (config[\"ApiKey\"] is { } apiKey) { env[\"API_KEY\"] = apiKey; }","handlingStrategy":"validation","validationCode":"foreach (var (k, v) in env)\n    if (v is null) throw new InvalidOperationException($\"Env var '{k}' has a null value; omit or default it.\");","typeGuard":"static bool EnvValuesValid(IDictionary<string, string?>? env) => env is null || env.Values.All(v => v is not null);","tryCatchPattern":"try { await command(); }\ncatch (DistributedApplicationException ex) when (ex.Message.Contains(\"requires a value\"))\n{ logger.LogError(ex, \"Env var with null value in process command; omit it or use empty string\"); }","preventionTips":["Only add env entries whose value is present","Represent 'unset' by omitting the key, not by null value","Use non-nullable dictionary types and null-checked configuration reads"],"tags":["process-command","environment-variables","null-value"],"backgroundTag":"missing-env-var","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"}