microsoft/aspire · error · DistributedApplicationException

Process command ' ' environment variable ' ' requires a…

Error message

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

What it means

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.

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

Example fix

// before
env["FEATURE_FLAG"] = builder.Configuration["FEATURE_FLAG"]; // null if unset
// after
env["FEATURE_FLAG"] = builder.Configuration["FEATURE_FLAG"] ?? "false";

Defensive patterns

Strategy: validation

Validate before calling

foreach (var (name, value) in envVars)
{
    if (string.IsNullOrEmpty(name)) throw new ArgumentException("Env var name required");
    if (value is null) throw new ArgumentException($"Env var '{name}' value is null");
}

Type guard

bool HasEnvVarValue(KeyValuePair<string, object?> kv) => kv.Value is not null;

Try / catch

try { builder.WithCommand(...); }
catch (DistributedApplicationException ex) { logger.LogError(ex, "Process command env var validation failed"); throw; }

Prevention

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

When it happens

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

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

Related errors

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

Appendix: source

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

        foreach (var argument in arguments)
        {
            if (argument is null)
            {
                throw new DistributedApplicationException($"Process command '{processCommandSpec.ExecutablePath}' arguments cannot contain null values.");
            }
        }

        var environmentVariables = processCommandSpec.EnvironmentVariables ?? new Dictionary<string, string>();
        foreach (var (name, value) in environmentVariables)
        {
            if (string.IsNullOrWhiteSpace(name))
            {
                throw new DistributedApplicationException($"Process command '{processCommandSpec.ExecutablePath}' environment variables require non-empty names.");
            }

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

        return new ProcessSpec(processCommandSpec.ExecutablePath)
        {
            WorkingDirectory = processCommandSpec.WorkingDirectory,
            ArgumentList = arguments,
            EnvironmentVariables = environmentVariables,
            InheritEnv = processCommandSpec.InheritEnvironmentVariables,
            StandardInputContent = processCommandSpec.StandardInputContent,
            KillEntireProcessTree = processCommandSpec.KillEntireProcessTree,
            ThrowOnNonZeroReturnCode = false,
            ResolveExecutablePath = true,
            RetainedOutputLineCount = commandOptions.MaxOutputLineCount,
            OnOutputData = output => context.Logger.LogDebug("{ExecutablePath} (stdout): {Output}", processCommandSpec.ExecutablePath, output),
            OnErrorData = error => context.Logger.LogDebug("{ExecutablePath} (stderr): {Error}", processCommandSpec.ExecutablePath, error)
        };
    }

View on GitHub (pinned to 25830f84bd)