microsoft/aspire · error · DistributedApplicationException

Process command requires a non-empty executable path.

Error message

Process command requires a non-empty executable path.

What it means

CreateProcessCommandSpec converts exported ProcessCommandSpecExportData into a ProcessCommandSpec and requires a non-whitespace ExecutablePath, since the process runner needs a program to launch. A blank/empty path causes this DistributedApplicationException when the command is invoked.

Solutions

1. Provide a concrete executable path, e.g. new("dotnet") or a resolved tool path.
2. Validate the path is non-whitespace in your factory before returning the spec.
3. Resolve platform-specific executables (e.g. 'dotnet' vs 'dotnet.exe', 'npm.cmd' on Windows) before registration or in the callback.

Example fix

// before
ExecutablePath = config["CliToolPath"] // empty when config missing
// after
var toolPath = config["CliToolPath"];
if (string.IsNullOrWhiteSpace(toolPath))
{
    throw new InvalidOperationException("CliToolPath is not configured.");
}
ExecutablePath = toolPath;

if (string.IsNullOrWhiteSpace(exportData.ExecutablePath))
    throw new InvalidOperationException("ExecutablePath must be a non-empty path before invoking the command.");

static bool HasExecutable(ProcessCommandSpecExportData? d) => d is { ExecutablePath: { } p } && !string.IsNullOrWhiteSpace(p);

try { await command(); }
catch (DistributedApplicationException ex) when (ex.Message.Contains("non-empty executable path"))
{ logger.LogError(ex, "Process command has no executable configured"); }

When it happens

Trigger: Register withProcessCommand with an ExecutablePath that is null, empty, or whitespace ('', ' '), or a createProcessSpec callback that returns export data with a missing ExecutablePath, then run the command.

Common situations: Config values for the executable not set (empty appsettings/env var); path built by joining segments where the base is null; polyglot hosts omitting the executablePath field; platform-specific binaries resolved to empty on the wrong OS.

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

• Process command environment variables require non-empty…
• Process command ' ' environment variables require non-empty…
• Process command arguments cannot contain null values.
• Process command environment variable
• Process command output line count must be greater than zero.

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

Appendix: source

Thrown at src/Aspire.Hosting/ResourceBuilderExtensions.cs:3371

    {
        return CreateProcessCommandSpec(new ProcessCommandSpecExportData
        {
            ExecutablePath = exportOptions.ExecutablePath,
            Arguments = exportOptions.Arguments,
            WorkingDirectory = exportOptions.WorkingDirectory,
            EnvironmentVariables = exportOptions.EnvironmentVariables,
            InheritEnvironmentVariables = exportOptions.InheritEnvironmentVariables,
            StandardInputContent = exportOptions.StandardInputContent,
            KillEntireProcessTree = exportOptions.KillEntireProcessTree
        });
    }

    private static ProcessCommandSpec CreateProcessCommandSpec(ProcessCommandSpecExportData exportData)
    {
        var executablePath = exportData.ExecutablePath;
        if (string.IsNullOrWhiteSpace(executablePath))
        {
            throw new DistributedApplicationException("Process command requires a non-empty executable path.");
        }

        var arguments = exportData.Arguments ?? [];
        foreach (var argument in arguments)
        {
            if (argument is null)
            {
                throw new DistributedApplicationException("Process command arguments cannot contain null values.");
            }
        }

        return new ProcessCommandSpec(executablePath)
        {
            WorkingDirectory = exportData.WorkingDirectory,
            Arguments = arguments.ToArray(),
            EnvironmentVariables = CreateEnvironmentVariables(exportData.EnvironmentVariables),
            InheritEnvironmentVariables = exportData.InheritEnvironmentVariables ?? true,
            StandardInputContent = exportData.StandardInputContent,

View on GitHub (pinned to 25830f84bd)