What causes "Command array cannot be empty." in microsoft/aspire?

Pass a non-empty command array, e.g. new[] { "dotnet", "MyApp.dll" }.

microsoft/aspire · error · ArgumentException

Command array cannot be empty.

Error message

Command array cannot be empty.

What it means

DockerfileStage.Cmd emits a CMD instruction from a command array. Docker's CMD requires at least one token, so an empty array would produce an invalid Dockerfile line. The method throws ArgumentNullException for null and ArgumentException ("Command array cannot be empty.") for a zero-length array on the command parameter.

Solutions

Pass a non-empty command array, e.g. new[] { "dotnet", "MyApp.dll" }.
Validate the command source before calling; throw or substitute a default when empty.
If the CMD should be omitted, skip the call instead of passing an empty array.

Example fix

// before
var args = extraArgs.Where(a => a.IsEnabled).ToArray();
stage.Cmd(args); // may be empty
// after
var args = extraArgs.Where(a => a.IsEnabled).ToArray();
if (args.Length > 0) stage.Cmd(args);

Defensive patterns

Strategy: validation

Validate before calling

if (command is null || command.Length == 0)
    throw new ArgumentException("CMD requires at least one token.", nameof(command));

Try / catch

try
{
    stage.Cmd(command);
}
catch (ArgumentException ex) when (ex.ParamName == nameof(command))
{
    logger.LogError(ex, "Refusing to emit empty CMD in Dockerfile stage {Stage}", stageName);
    throw;
}

Prevention

Never build the command array with filters that can legitimately return empty — check Length first.
Split strings with StringSplitOptions.RemoveEmptyEntries and validate the result.
Skip the Cmd() call when no command is intended rather than passing [].
Snapshot-test generated Dockerfiles so empty instructions fail review.

When it happens

Trigger: stage.Cmd(Array.Empty<string>()), stage.Cmd(args.Where(...).ToArray()) where the filter matched nothing, or stage.Cmd(config["cmd"].Split(' ')) resolving to an empty array.

Common situations: Building Dockerfiles programmatically where the command comes from options/config that was empty; filtering arguments with a predicate that removed all entries; splitting an empty string, which yields an array with one empty element or an empty array depending on options.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ApplicationModel/Docker/DockerfileStage.cs:201

    public DockerfileStage Expose(int port)
    {
        ArgumentOutOfRangeException.ThrowIfNegativeOrZero(port);
        _statements.Add(new DockerfileExposeStatement(port));
        return this;
    }

    /// <summary>
    /// Adds a CMD statement to set the default command.
    /// </summary>
    /// <param name="command">The command to execute.</param>
    /// <returns>The current stage.</returns>
    [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
    public DockerfileStage Cmd(string[] command)
    {
        ArgumentNullException.ThrowIfNull(command);
        if (command.Length == 0)
        {
            throw new ArgumentException("Command array cannot be empty.", nameof(command));
        }
        _statements.Add(new DockerfileCmdStatement(command));
        return this;
    }

    /// <summary>
    /// Adds an ENTRYPOINT statement to set the container entrypoint.
    /// </summary>
    /// <param name="command">The entrypoint command to execute.</param>
    /// <returns>The current stage.</returns>
    [Experimental("ASPIREDOCKERFILEBUILDER001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
    public DockerfileStage Entrypoint(string[] command)
    {
        ArgumentNullException.ThrowIfNull(command);
        if (command.Length == 0)
        {
            throw new ArgumentException("Command array cannot be empty.", nameof(command));
        }

View on GitHub (pinned to 25830f84bd)