microsoft/aspire · error · DistributedApplicationException

Process command output line count must be greater than zero.

Error message

Process command output line count must be greater than zero.

What it means

When converting exported process-command options into internal ProcessCommandOptions, Aspire validates MaxOutputLineCount, which caps how many lines of process output are retained/returned. A value of zero or negative would make the bounded tail meaningless, so a DistributedApplicationException is thrown at command registration time.

Solutions

1. Set MaxOutputLineCount to a positive integer (e.g. 100).
2. Omit MaxOutputLineCount entirely to keep the default; do not use 0 as 'unlimited'.
3. Validate any user/config-supplied value before passing it into options (reject <= 0).

Example fix

// before
options.MaxOutputLineCount = int.Parse(config["MaxOutputLines"]); // 0 when unset
// after
if (int.TryParse(config["MaxOutputLines"], out var n) && n > 0)
{
    options.MaxOutputLineCount = n;
}

if (options.MaxOutputLineCount is { } n && n <= 0)
    throw new ArgumentOutOfRangeException(nameof(options.MaxOutputLineCount), n, "Must be > 0.");

static bool IsValidLineCount(int? n) => n is null or > 0;

try { builder.WithProcessCommandExport(name, display, options); }
catch (DistributedApplicationException ex) when (ex.Message.Contains("line count must be greater than zero"))
{ logger.LogError(ex, "Fix MaxOutputLineCount in options for {Command}", name); }

When it happens

Trigger: Call withProcessCommand (export path) with options where MaxOutputLineCount is set to 0 or a negative number; the exception is thrown synchronously while registering the command, not when the command runs.

Common situations: Config-driven option values where a config file or environment variable supplies 0 or -1 as a 'disabled' sentinel; string-to-number parsing producing 0 for empty values; copying defaults incorrectly between code and polyglot options.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Process command arguments cannot contain null values.
• Process command ' ' arguments cannot contain null values.
• Address prefix must be a string or a parameter resource…
• Address prefix must be omitted, a string, or a parameter…
• All resources should be of the same kind when calling…

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

Appendix: source

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

    private static ProcessCommandOptions CreateProcessCommandOptions(ProcessCommandResultExportOptions? exportOptions)
    {
        var commandOptions = new ProcessCommandOptions();
        if (exportOptions is null)
        {
            return commandOptions;
        }

        if (exportOptions.CommandOptions is { } commonOptions)
        {
            ApplyCommandOptions(commandOptions, commonOptions);
        }

        if (exportOptions.MaxOutputLineCount is { } maxOutputLineCount)
        {
            if (maxOutputLineCount <= 0)
            {
                throw new DistributedApplicationException("Process command output line count must be greater than zero.");
            }

            commandOptions.MaxOutputLineCount = maxOutputLineCount;
        }

        if (exportOptions.DisplayImmediately is { } displayImmediately)
        {
            commandOptions.DisplayImmediately = displayImmediately;
        }

        // Some generated clients serialize default collection values as empty arrays. Treat an empty exported list as
        // omitted so those clients preserve the default [0] success code.
        if (exportOptions.SuccessExitCodes is { Count: > 0 } successExitCodes)
        {
            commandOptions.SuccessExitCodes = successExitCodes.ToArray();
        }

        return commandOptions;

View on GitHub (pinned to 25830f84bd)