{"record":{"id":"cff5826599a4d0e0","repo":"microsoft/aspire","slug":"process-command-processcommandspec-executablepath-cff582","errorCode":null,"errorMessage":"Process command '{processCommandSpec.ExecutablePath}' 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":3441,"sourceCode":"        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        }\n\n        var environmentVariables = processCommandSpec.EnvironmentVariables ?? new Dictionary<string, string>();\n        foreach (var (name, value) in environmentVariables)\n        {\n            if (string.IsNullOrWhiteSpace(name))\n            {\n                throw new DistributedApplicationException($\"Process command '{processCommandSpec.ExecutablePath}' environment variables require non-empty names.\");\n            }\n\n            if (value is null)\n            {\n                throw new DistributedApplicationException($\"Process command '{processCommandSpec.ExecutablePath}' environment variable '{name}' requires a value.\");\n            }\n        }\n\n        return new ProcessSpec(processCommandSpec.ExecutablePath)\n        {\n            WorkingDirectory = processCommandSpec.WorkingDirectory,\n            ArgumentList = arguments,\n            EnvironmentVariables = environmentVariables,\n            InheritEnv = processCommandSpec.InheritEnvironmentVariables,\n            StandardInputContent = processCommandSpec.StandardInputContent,\n            KillEntireProcessTree = processCommandSpec.KillEntireProcessTree,\n            ThrowOnNonZeroReturnCode = false,\n            ResolveExecutablePath = true,\n            RetainedOutputLineCount = commandOptions.MaxOutputLineCount,\n            OnOutputData = output => context.Logger.LogDebug(\"{ExecutablePath} (stdout): {Output}\", processCommandSpec.ExecutablePath, output),\n            OnErrorData = error => context.Logger.LogDebug(\"{ExecutablePath} (stderr): {Error}\", processCommandSpec.ExecutablePath, error)\n        };\n    }","sourceCodeStart":3423,"sourceCodeEnd":3459,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/ResourceBuilderExtensions.cs#L3423-L3459","documentation":"Aspire validates that every environment variable added to a process command spec has a non-null value before constructing the ProcessSpec. A null value means the dictionary passed to the command builder contained an entry without a value, which Aspire treats as a programming error rather than silently passing an empty value. It throws DistributedApplicationException at model-building time.","triggerScenarios":"Calling a WithCommand/WithProcessCommand-style API whose CommandOptions.EnvironmentVariables dictionary contains a key mapped to a null value; or a config lookup (e.g. builder.Configuration[\"KEY\"]) returned null and was passed directly as an environment variable value.","commonSituations":"Reading an appsettings key or environment variable that does not exist and passing the null result straight into EnvironmentVariables; refactoring code so a value assignment was dropped; conditional logic that leaves a dictionary entry null.","solutions":["Ensure every environment variable value is non-null before passing it (e.g. use ?? string.Empty or ?? throw with a clear message)","Check that the configuration key / environment variable you read actually exists and has a value","If the variable is genuinely optional, omit it from the dictionary instead of adding a null value"],"exampleFix":"// before\nenv[\"FEATURE_FLAG\"] = builder.Configuration[\"FEATURE_FLAG\"]; // null if unset\n// after\nenv[\"FEATURE_FLAG\"] = builder.Configuration[\"FEATURE_FLAG\"] ?? \"false\";","handlingStrategy":"validation","validationCode":"foreach (var (name, value) in envVars)\n{\n    if (string.IsNullOrEmpty(name)) throw new ArgumentException(\"Env var name required\");\n    if (value is null) throw new ArgumentException($\"Env var '{name}' value is null\");\n}","typeGuard":"bool HasEnvVarValue(KeyValuePair<string, object?> kv) => kv.Value is not null;","tryCatchPattern":"try { builder.WithCommand(...); }\ncatch (DistributedApplicationException ex) { logger.LogError(ex, \"Process command env var validation failed\"); throw; }","preventionTips":["Never pass configuration lookups directly as env var values without a ?? fallback","Use string or object non-nullable types for env var values where possible"],"tags":["process","environment-variables","null-value","aspire-hosting"],"backgroundTag":"null-argument","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"}