microsoft/aspire · error · ArgumentException

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

Error message

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

What it means

ProcessCommandSpec validates its required executablePath constructor argument with IsNullOrWhiteSpace and throws ArgumentException when it is null, empty, or whitespace. The executable path is fundamental to launching the process, so an empty value cannot be defaulted.

Solutions

1. Pass a real executable path or command name, e.g. new ProcessCommandSpec("dotnet", ...)
2. Validate the source value before constructing: if (string.IsNullOrWhiteSpace(path)) throw ...
3. If the path comes from an env var, fall back to a known default or fail with a clearer message

Example fix

// before
var spec = new ProcessCommandSpec(env["TOOL_PATH"], ...);
// after
var spec = new ProcessCommandSpec(
    string.IsNullOrWhiteSpace(env["TOOL_PATH"]) ? "tool" : env["TOOL_PATH"], ...);

if (string.IsNullOrWhiteSpace(executablePath)) throw new ArgumentException("Executable path is required.");
var spec = new ProcessCommandSpec(executablePath, ...);

bool HasExecutable([NotNullWhen(true)] string? p) => !string.IsNullOrWhiteSpace(p);

try { var spec = new ProcessCommandSpec(path, ...); } catch (ArgumentException ex) { /* resolve path from env/config fallback */ }

When it happens

Trigger: new ProcessCommandSpec(null/""/" ", ...) — passing an unresolved variable, an empty config value, or a path derived from a failed lookup.

Common situations: A tool name resolved from an environment variable or config key that was unset; a path computed by string concatenation that yielded empty; trimming a value that was only whitespace.

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

• At least one process command success exit code must be…
• Launch arguments must contain at least one entry.
• Object must implement IManifestExpressionProvider
• Object must implement IValueProvider
• Process command ' ' environment variable ' ' requires a…

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

Appendix: source

Thrown at src/Aspire.Hosting/ApplicationModel/ProcessCommandSpec.cs:27

/// Describes a local process that is started when a process-backed resource command executes.
/// </summary>
/// <param name="executablePath">
/// The executable path or command name to start. Command names are resolved from the AppHost process PATH.
/// </param>
[Experimental("ASPIREPROCESSCOMMAND001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
public sealed class ProcessCommandSpec(string executablePath)
{
    /// <summary>
    /// Gets the executable path or command name to start.
    /// </summary>
    /// <remarks>
    /// <para>
    /// Command names without directory separators are resolved from the AppHost process PATH before starting the process.
    /// </para>
    /// </remarks>
    public string ExecutablePath { get; } = !string.IsNullOrWhiteSpace(executablePath)
        ? executablePath
        : throw new ArgumentException("The executable path cannot be null, empty, or whitespace.", nameof(executablePath));

    /// <summary>
    /// Gets or sets the working directory for the process.
    /// </summary>
    public string? WorkingDirectory { get; init; }

    /// <summary>
    /// Gets or sets the command-line arguments for the process.
    /// </summary>
    /// <remarks>
    /// <para>
    /// Arguments are passed using <see cref="System.Diagnostics.ProcessStartInfo.ArgumentList"/> so that each item is
    /// escaped according to the current platform's process-start rules.
    /// </para>
    /// </remarks>
    public IReadOnlyList<string> Arguments { get; init; } = [];

    /// <summary>

View on GitHub (pinned to 25830f84bd)