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

Filter empty strings: args.Where(a => !string.IsNullOrEmpty(a)).ToArray()

microsoft/aspire · error · ArgumentException

Array params contains empty item

Error message

Array params contains empty item: [{values}]

What it means

ThrowIfNullOrContainsIsNullOrEmpty throws ArgumentException when the string[] args parameter to DistributedApplicationTestingBuilder.CreateAsync/Create contains an empty string element. Empty entries would be forwarded as meaningless arguments to the app host, so they are rejected with a message listing the full args array.

Solutions

Filter empty strings: args.Where(a => !string.IsNullOrEmpty(a)).ToArray()
Guard env-var-derived args for empty input before splitting
Only pass well-formed "--name=value" style arguments

Example fix

// before
var extra = Environment.GetEnvironmentVariable("EXTRA_ARGS")?.Split(' ') ?? []; // may contain ""
await DistributedApplicationTestingBuilder.CreateAsync<Projects.AppHost>(extra);
// after
var extra = (Environment.GetEnvironmentVariable("EXTRA_ARGS") ?? "")
    .Split(' ', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
await DistributedApplicationTestingBuilder.CreateAsync<Projects.AppHost>(extra);

Defensive patterns

Strategy: validation

Validate before calling

if (args.Any(string.IsNullOrEmpty)) throw new InvalidOperationException("args contains empty items");

Type guard

static string[] NonEmptyArgs(IEnumerable<string?> source) =>
    source.Where(a => !string.IsNullOrEmpty(a)).ToArray()!;

Try / catch

try { await DistributedApplicationTestingBuilder.CreateAsync<Projects.AppHost>(args); }
catch (ArgumentException ex) when (ex.ParamName == "args")
{
    // filter empty entries and retry
}

Prevention

Use RemoveEmptyEntries when splitting strings into args
Guard env-var-sourced arguments for empty values
Keep helper methods that build args returning sanitized arrays

When it happens

Trigger: Calling DistributedApplicationTestingBuilder.CreateAsync<T>(new[] { "" }) or passing arrays assembled from empty config values / split strings that produced empty entries (e.g. "" .Split(',') on an empty env var).

Common situations: Reading CLI args from an empty environment variable and splitting; concatenating optional flags where missing values yield ""; copy-pasted test setup with leftover empty strings.

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/1f34cffd96881a9a. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting.Testing/DistributedApplicationTestingBuilder.cs:450

            // Tests get the credential through GetDashboardUrlAsync instead.
            ["AppHost:SuppressDashboardLoginUrlInStartupSummary"] = "true",
            [KnownConfigNames.DashboardSuppressBrowserTokenInOutput] = "true"
        });
    }

    private static void 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));
            }
        }
    }

    /// <summary>
    /// The dashboard testing configuration resolved during builder construction. Carried as a single value so the
    /// pre-construction and post-construction halves of the configuration cannot drift apart.
    /// </summary>
    private readonly record struct DashboardTestingState(bool Enabled, string? BrowserToken, string? ResourceServiceApiKey);

    private sealed class SuspendingDistributedApplicationFactory(
        Type entryPoint,
        string[] args,
        DistributedApplicationTestingBuilderOptions? testingOptions,
        Action<DistributedApplicationOptions, HostApplicationBuilderSettings> configureBuilder)
        : DistributedApplicationFactory(entryPoint, args)
    {
        private readonly SemaphoreSlim _continueBuilding = new(0);

View on GitHub (pinned to 25830f84bd)