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

Inspect the args array passed to AddPythonApp and remove/skip null entries.

microsoft/aspire · error · ArgumentNullException

Array params contains null item

Error message

Array params contains null item: [{values}]

What it means

AddPythonApp validates its scriptArgs collection via ThrowIfNullOrContainsIsNullOrEmpty. If any element of scriptArgs is a null reference, it throws ArgumentNullException naming scriptArgs and including the full argument list in the message.

Solutions

Inspect the args array passed to AddPythonApp and remove/skip null entries.
Add a filter before building: args = candidateArgs.Where(a => a is not null).ToArray().
Use ArgumentNullException.ThrowIfNull on individual computed arguments before adding them.
Read the list shown in the message ([values]) to find the null position.

Example fix

// before
builder.AddPythonApp("py", "main.py", "--flag", null, "other");
// after
builder.AddPythonApp("py", "main.py", "--flag", "other");

Defensive patterns

Strategy: validation

Validate before calling

if (args.Any(a => a is null))
    throw new InvalidOperationException("scriptArgs contains a null entry.");

Type guard

static bool HasNullArg(string?[] args) => args.Any(a => a is null);

Try / catch

try
{
    builder.AddPythonApp("py", "main.py", args);
}
catch (ArgumentNullException ex)
{
    logger.LogError(ex, "Null entry in python args: {Args}", ex.Message);
}

Prevention

Filter arrays with Where(a => a is not null) before passing script args.
Validate config-driven arguments before building the args array.
Avoid appending results of possibly-null lookups directly into arg collections.

When it happens

Trigger: Passing an array containing a null element to AddPythonApp, e.g. args built dynamically where one entry was never assigned: new[] { "--flag", null }.

Common situations: Dynamically assembled argument arrays from config or environment lookups returning null; conditional argument building that appends null instead of skipping.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Python/PythonAppResourceBuilderExtensions.cs:743

                stage.Entrypoint(["python", "-m", entrypoint]);
                break;
            case EntrypointType.Executable:
                stage.Entrypoint([entrypoint]);
                break;
        }
    }

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

    /// <summary>
    /// Resolves the default virtual environment path by checking multiple candidate locations.
    /// </summary>
    /// <param name="builder">The distributed application builder.</param>
    /// <param name="appDirectory">The Python app directory (relative to AppHost).</param>
    /// <param name="virtualEnvironmentPath">The relative virtual environment path (e.g., ".venv").</param>
    /// <returns>The resolved virtual environment path.</returns>
    private static string ResolveDefaultVirtualEnvironmentPath(IDistributedApplicationBuilder builder, string appDirectory, string virtualEnvironmentPath)
    {
        var appDirectoryFullPath = Path.GetFullPath(appDirectory, builder.AppHostDirectory);

        // Walk up from the Python app directory looking for the virtual environment

View on GitHub (pinned to 25830f84bd)