microsoft/aspire · error · DistributedApplicationException

Process command arguments cannot contain null values.

Error message

Process command arguments cannot contain null values.

What it means

While converting exported ProcessCommandSpecExportData, CreateProcessCommandSpec walks the Arguments collection and rejects any null element with a DistributedApplicationException. Arguments become the process's ArgumentList, where null entries are not representable.

Solutions

Remove null entries from Arguments before returning the spec (e.g. args.Where(a => a is not null)).
Build arguments by only appending values that are actually present.
Replace null placeholders with real values or omit the argument entirely.

Example fix

// before
Arguments = ["run", optionalArg /* may be null */, "--verbose"]
// after
var args = new List<string> { "run", "--verbose" };
if (optionalArg is not null) { args.Insert(1, optionalArg); }
Arguments = args;

Defensive patterns

Strategy: validation

Validate before calling

var bad = exportData.Arguments?.IndexOf(null) ?? -1;
if (bad >= 0) throw new InvalidOperationException($"Argument at index {bad} is null.");

Type guard

static bool HasNoNullArgs(IEnumerable<string?>? args) => args?.All(a => a is not null) ?? true;

Try / catch

try { await command(); }
catch (DistributedApplicationException ex) when (ex.Message.Contains("arguments cannot contain null"))
{ logger.LogError(ex, "Filter nulls from process command arguments"); }

Prevention

Use args.Where(a => a is not null) when building argument lists from optional values
Avoid null placeholders in collection expressions
Test each command's execution path in unit tests

When it happens

Trigger: Pass Arguments containing a null entry to withProcessCommand export options, or return export data whose Arguments list includes null (common when building lists conditionally in a polyglot host), then execute the command.

Common situations: Building argument arrays by concatenating optional values where a missing value contributes null instead of being filtered; deserialized JSON argument lists with explicit null items; placeholder entries intended to be replaced later.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

            StandardInputContent = exportOptions.StandardInputContent,
            KillEntireProcessTree = exportOptions.KillEntireProcessTree
        });
    }

    private static ProcessCommandSpec CreateProcessCommandSpec(ProcessCommandSpecExportData exportData)
    {
        var executablePath = exportData.ExecutablePath;
        if (string.IsNullOrWhiteSpace(executablePath))
        {
            throw new DistributedApplicationException("Process command requires a non-empty executable path.");
        }

        var arguments = exportData.Arguments ?? [];
        foreach (var argument in arguments)
        {
            if (argument is null)
            {
                throw new DistributedApplicationException("Process command arguments cannot contain null values.");
            }
        }

        return new ProcessCommandSpec(executablePath)
        {
            WorkingDirectory = exportData.WorkingDirectory,
            Arguments = arguments.ToArray(),
            EnvironmentVariables = CreateEnvironmentVariables(exportData.EnvironmentVariables),
            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)

View on GitHub (pinned to 25830f84bd)