microsoft/aspire · error · DistributedApplicationException

Process command ' ' arguments cannot contain null values.

Error message

Process command '{processCommandSpec.ExecutablePath}' arguments cannot contain null values.

What it means

CreateProcessSpec performs a second validation pass on the final ProcessCommandSpec just before launching the process. It rejects any null element in Arguments with a DistributedApplicationException that includes the executable path, because ArgumentList passed to the OS cannot contain nulls.

Solutions

Filter nulls out of Arguments before constructing the spec (args.Where(a => a is not null).ToArray()).
Append arguments only when their source value is non-null.
Assert/validate your factory output in tests covering command execution.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

var bad = processCommandSpec.Arguments?.IndexOf(null) ?? -1;
if (bad >= 0) throw new InvalidOperationException($"Spec for '{processCommandSpec.ExecutablePath}' has null argument at {bad}.");

Type guard

static bool ArgsValid(ProcessCommandSpec? s) => s is null || s.Arguments?.All(a => a is not null) != false;

Try / catch

try { await command(); }
catch (DistributedApplicationException ex) when (ex.Message.Contains("arguments cannot contain null"))
{ logger.LogError(ex, "Null argument in spec for {Exe}", exePath); }

Prevention

Filter nulls in C# factories exactly as in export callbacks
Append arguments conditionally instead of interpolating nulls
Snapshot-test spec factories with representative context data

When it happens

Trigger: Return a ProcessCommandSpec from a C# processSpecFactory whose Arguments list contains a null entry, then invoke the command; this triggers even though the earlier export-path check (error 1885) only runs on the export route.

Common situations: C# factories building argument lists conditionally where nulls slip in; spreading optional values with collection expressions; passing values read from configuration that deserialize to null.

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/0ada56e5e4acd8f9. Report an issue: GitHub.

Appendix: source

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

            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.");
            }
        }

        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)

View on GitHub (pinned to 25830f84bd)