What causes "Array params contains null item: [{values}]" in microsoft/aspire?

Filter out null entries before constructing the factory: args.Where(a => a is not null).ToArray()

microsoft/aspire · error · ArgumentNullException

Array params contains null item

Error message

Array params contains null item: [{values}]

What it means

DistributedApplicationFactory validates the args array passed to its constructor before starting the app host. A null element inside the args array is treated as a programming error, so it throws ArgumentNullException naming the args parameter and listing all values.

Solutions

Filter out null entries before constructing the factory: args.Where(a => a is not null).ToArray()
Fix the code producing the args array so nulls never enter it (default missing values to empty string or omit them)
Add a guard/assertion in test setup that validates all args are non-null
If a null signals a missing required setting, resolve that setting explicitly and fail with a clear message

Example fix

// before
var args = new string[] { "--DcpPublisher:LifeCycle=false", null };
var factory = new DistributedApplicationFactory<Program>(args);
// after
var args = new[] { "--DcpPublisher:LifeCycle=false" }.Where(a => !string.IsNullOrEmpty(a)).ToArray();
var factory = new DistributedApplicationFactory<Program>(args);

Defensive patterns

Strategy: validation

Validate before calling

static string[] ValidateArgs(string?[] args) =>
    args.All(a => a is not null)
        ? args!.
        : throw new ArgumentException("args contains null entries", nameof(args));

Type guard

static bool HasNoNulls(string?[] args) => Array.TrueForAll(args, a => a is not null);

Try / catch

try
{
    var factory = new DistributedApplicationFactory<Program>(args);
}
catch (ArgumentNullException ex) when (ex.ParamName == "args")
{
    throw new InvalidOperationException("Test args must not contain null entries", ex);
}

Prevention

Build args with collection expressions and string literals, never nullable placeholders
Use string.Split with RemoveEmptyEntries when deriving args from strings
Sanitize config-derived values: skip null/empty instead of passing them through
Assert on composed args arrays in test setup helpers

When it happens

Trigger: Calling new DistributedApplicationFactory<TEntryPoint>(args) (directly or via a factory base class) with an array such as new string[] { null } or an array containing a null element, e.g. from string.Split results or uninitialized entries.

Common situations: Building args dynamically from configuration or environment parsing where a missing value yields null; passing the result of string.Split with missing segments; test setup code assembling CLI args programmatically.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Testing/DistributedApplicationFactory.cs:161

    /// <summary>
    /// Called when the application has been built.
    /// </summary>
    /// <param name="application">The application.</param>
    protected virtual void OnBuilt(DistributedApplication application)
    {
    }

    private static string[] ThrowIfNullOrContainsIsNullOrEmpty(string[] args)
    {
        ArgumentNullException.ThrowIfNull(args);
        foreach (var arg in args)
        {
            if (string.IsNullOrEmpty(arg))
            {
                var values = string.Join(", ", args);
                if (arg is null)
                {
                    throw new ArgumentNullException(nameof(args), $"Array params contains null item: [{values}]");
                }
                throw new ArgumentException($"Array params contains empty item: [{values}]", nameof(args));
            }
        }
        return args;
    }

    private void OnBuiltCore(DistributedApplication application)
    {
        _shutdownTimeout = application.Services.GetService<IOptions<HostOptions>>()?.Value.ShutdownTimeout ?? _shutdownTimeout;
        _appTcs.TrySetResult(application);
        OnBuilt(application);
    }

    private static void PreConfigureBuilderOptions(
        DistributedApplicationOptions applicationOptions,
        HostApplicationBuilderSettings hostBuilderOptions,
        string[] args,

View on GitHub (pinned to 25830f84bd)