microsoft/aspire · error · DistributedApplicationException

Process command environment variables require non-empty…

Error message

Process command environment variables require non-empty names.

What it means

CreateEnvironmentVariables validates the EnvironmentVariables dictionary of exported process-command data. An environment variable name that is null, empty, or whitespace cannot be passed to the OS process, so a DistributedApplicationException is thrown.

Solutions

Ensure every key in EnvironmentVariables is a non-empty, non-whitespace string.
Validate/sanitize names before adding them (skip or throw on blank keys at construction time).
If names come from parsing, fix the parser to reject or repair empty name segments.

Example fix

// before
env[line.Split('=')[0]] = line.Split('=')[1]; // name can be empty for '=value'
// after
var parts = line.Split('=', 2);
if (!string.IsNullOrWhiteSpace(parts[0]))
{
    env[parts[0]] = parts[1];
}

Defensive patterns

Strategy: validation

Validate before calling

foreach (var k in exportData.EnvironmentVariables?.Keys ?? Enumerable.Empty<string>())
    if (string.IsNullOrWhiteSpace(k)) throw new InvalidOperationException("Blank env var name in process command options.");

Type guard

static bool EnvNamesValid(IDictionary<string, string>? env) => env is null || env.Keys.All(k => !string.IsNullOrWhiteSpace(k));

Try / catch

try { await command(); }
catch (DistributedApplicationException ex) when (ex.Message.Contains("environment variables require non-empty names"))
{ logger.LogError(ex, "A blank environment variable name was supplied"); }

Prevention

Sanitize parsed config keys before adding to env dictionaries
Reject empty keys at dictionary construction time
Log env var names (not values) during setup to spot blanks early

When it happens

Trigger: Provide EnvironmentVariables with a blank key ('', ' ', or null after deserialization) in withProcessCommand export options or in ProcessCommandSpecExportData returned by createProcessSpec, then run the command.

Common situations: Building a dictionary from parsed config lines where the name portion is empty; JSON objects deserialized with empty keys; string interpolation bugs producing keys that collapse to empty.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

            InheritEnvironmentVariables = exportData.InheritEnvironmentVariables ?? true,
            StandardInputContent = exportData.StandardInputContent,
            KillEntireProcessTree = exportData.KillEntireProcessTree ?? true
        };
    }

    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)
        {

View on GitHub (pinned to 25830f84bd)