microsoft/aspire · error · ArgumentException

The executable command cannot be null, empty, or whitespace.

Error message

The executable command cannot be null, empty, or whitespace.

What it means

ExecutableLaunchPlan.Command validates at construction that the executable command is a non-empty, non-whitespace string, throwing ArgumentException otherwise. This is an eager constructor guard ensuring launch plans always have a runnable command.

Solutions

1. Ensure the resource has an ExecutableAnnotation with a valid non-empty Command before creating the launch plan
2. Validate/normalize the command string upstream and fail earlier with a clearer message if empty
3. Fix custom or test code that constructs ExecutableLaunchPlan directly to supply a real command

Example fix

// before
var plan = new ExecutableLaunchPlan(command: string.Empty, workingDirectory: dir, args: [], env: new());
// after
var plan = new ExecutableLaunchPlan(command: "dotnet", workingDirectory: dir, args: [projectPath], env: new());

if (string.IsNullOrWhiteSpace(command))
  throw new ArgumentException("Executable command must be provided before building a launch plan.", nameof(command));

bool IsValidCommand(string? command) => !string.IsNullOrWhiteSpace(command);

try { var plan = new ExecutableLaunchPlan(command, wd, args, env); } catch (ArgumentException ex) when (ex.Message.Contains("executable command")) { /* supply a valid command or surface config error */ }

When it happens

Trigger: Constructing ExecutableLaunchPlan with null, "", or whitespace for the command parameter — e.g., when ExecutableAnnotation.Command was unset/empty and the recipe forwarded it, or custom code builds a launch plan directly.

Common situations: A resource pipeline removed or never set the executable command annotation; parsing launch metadata (launchSettings profiles) that yielded an empty command; test code constructing the plan with placeholder 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

• Array params contains empty item
• Array params contains null item
• Endpoint and repository must both be strings or parameter…
• Image must be a string or AddContainerOptions.
• A circular lifetime reference was detected for resource

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

Appendix: source

Thrown at src/Aspire.Hosting/ApplicationModel/ExecutableLaunchRecipe.cs:211

/// </param>
/// <param name="environmentVariables">The resolved environment variables for the executable.</param>
/// <param name="launchConfigurations">The serialized launch configurations supplied to an IDE.</param>
/// <param name="displayArguments">The arguments projected into the dashboard command line.</param>
internal sealed class ExecutableLaunchPlan(
    string command,
    string workingDirectory,
    ExecutableLaunchMechanism mechanism,
    IReadOnlyList<string>? arguments,
    IEnumerable<KeyValuePair<string, string>> environmentVariables,
    IEnumerable<JsonElement> launchConfigurations,
    IEnumerable<ExecutableLaunchArgument> displayArguments)
{
    /// <summary>
    /// Gets the executable path or command name.
    /// </summary>
    public string Command { get; } = !string.IsNullOrWhiteSpace(command)
        ? command
        : throw new ArgumentException("The executable command cannot be null, empty, or whitespace.", nameof(command));

    /// <summary>
    /// Gets the working directory for the executable.
    /// </summary>
    public string WorkingDirectory { get; } = workingDirectory ?? throw new ArgumentNullException(nameof(workingDirectory));

    /// <summary>
    /// Gets the selected launch mechanism.
    /// </summary>
    public ExecutableLaunchMechanism Mechanism { get; } = mechanism;

    /// <summary>
    /// Gets the arguments for the selected mechanism, or <see langword="null"/> when they are inherited by the IDE.
    /// </summary>
    public IReadOnlyList<string>? Arguments { get; } = arguments?.ToArray();

    /// <summary>
    /// Gets the resolved environment variables for the executable.

View on GitHub (pinned to 25830f84bd)