microsoft/aspire · error · DistributedApplicationException

Process command environment variable

Error message

Process command environment variable '{name}' requires a value.

What it means

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.

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.

Example fix

// before
env["API_KEY"] = config["ApiKey"]; // null when not configured
// after
if (config["ApiKey"] is { } apiKey) { env["API_KEY"] = apiKey; }

Defensive patterns

Strategy: validation

Validate before calling

foreach (var (k, v) in env)
    if (v is null) throw new InvalidOperationException($"Env var '{k}' has a null value; omit or default it.");

Type guard

static bool EnvValuesValid(IDictionary<string, string?>? env) => env is null || env.Values.All(v => v is not null);

Try / catch

try { await command(); }
catch (DistributedApplicationException ex) when (ex.Message.Contains("requires a value"))
{ logger.LogError(ex, "Env var with null value in process command; omit it or use empty string"); }

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ResourceBuilderExtensions.cs:3411

    private static Dictionary<string, string> CreateEnvironmentVariables(IReadOnlyDictionary<string, string>? environmentVariables)
    {
        var result = new Dictionary<string, string>(StringComparer.Ordinal);
        if (environmentVariables is null)
        {
            return result;
        }

        foreach (var (name, value) in environmentVariables)
        {
            if (string.IsNullOrWhiteSpace(name))
            {
                throw new DistributedApplicationException("Process command environment variables require non-empty names.");
            }

            if (value is null)
            {
                throw new DistributedApplicationException($"Process command environment variable '{name}' requires a value.");
            }

            result.Add(name, value);
        }

        return result;
    }

    private static ProcessSpec CreateProcessSpec(ExecuteCommandContext context, ProcessCommandSpec processCommandSpec, ProcessCommandOptions commandOptions)
    {
        var arguments = processCommandSpec.Arguments ?? [];
        foreach (var argument in arguments)
        {
            if (argument is null)
            {
                throw new DistributedApplicationException($"Process command '{processCommandSpec.ExecutablePath}' arguments cannot contain null values.");
            }
        }

View on GitHub (pinned to 25830f84bd)