microsoft/aspire · error · ArgumentOutOfRangeException

Unsupported completion state.

Error message

Unsupported completion state.

What it means

PipelineExports.ParseCompletionState maps a completion-state string to CompletionState and throws ArgumentOutOfRangeException for any string outside the accepted set: inprogress/in_progress/in-progress, completed, completedwithwarning/* variants, and completedwitherror/* variants. It is shared by CompleteStep, CompleteStepMarkdown, CompleteTask, and CompleteTaskMarkdown.

Solutions

1. Use an accepted state string: inprogress, completed, completedwithwarning, or completedwitherror (hyphen/underscore variants also accepted).
2. Translate foreign state names before calling (e.g., failed -> completedwitherror, done -> completed).
3. Trim/normalize the incoming string to avoid stray whitespace.

Example fix

// before
CompleteStep("step1", "Done", "done");
// after
CompleteStep("step1", "Done", "completed");

var allowed = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
    { "inprogress", "in_progress", "in-progress", "completed", "completedwithwarning", "completed_with_warning", "completed-with-warning", "completedwitherror", "completed_with_error", "completed-with-error" };
if (!allowed.Contains(completionState))
{
    throw new ArgumentException($"Unknown completion state '{completionState}'.");
}

bool IsKnownCompletionState(string s) => s.ToLowerInvariant() is "inprogress" or "in_progress" or "in-progress" or "completed" or "completedwithwarning" or "completedwitherror";

try
{
    CompleteStep(name, message, completionState);
}
catch (ArgumentOutOfRangeException ex) when (ex.ParamName == "completionState")
{
    CompleteStep(name, message, completionState.Contains("error") ? "completedwitherror" : "completed");
}

When it happens

Trigger: Calling CompleteStep/CompleteStepMarkdown/CompleteTask/CompleteTaskMarkdown with a state string such as "done", "failed", "success", "InProgress ", or an unsupported variant.

Common situations: Mapping states from another system's vocabulary (done/failed/succeeded) directly into the pipeline completion APIs; hand-written state strings in scripts.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• The requiredBy parameter must be a string or IEnumerable
• Unsupported log level.
• A step with the name
• Address prefix must be a string or a parameter resource…
• Address prefix must be omitted, a string, or a parameter…

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

Appendix: source

Thrown at src/Aspire.Hosting/Ats/PipelineExports.cs:202

    public static Task CompleteTaskMarkdown(this IReportingTask reportingTask, string markdownString, string completionState = "completed", CancellationToken cancellationToken = default)
    {
        ArgumentNullException.ThrowIfNull(reportingTask);
        ArgumentNullException.ThrowIfNull(markdownString);

        return reportingTask.CompleteAsync(new MarkdownString(markdownString), ParseCompletionState(completionState), cancellationToken);
    }

    private static CompletionState ParseCompletionState(string completionState)
    {
        ArgumentNullException.ThrowIfNull(completionState);

        return completionState.ToLowerInvariant() switch
        {
            "inprogress" or "in_progress" or "in-progress" => CompletionState.InProgress,
            "completed" => CompletionState.Completed,
            "completedwithwarning" or "completed_with_warning" or "completed-with-warning" => CompletionState.CompletedWithWarning,
            "completedwitherror" or "completed_with_error" or "completed-with-error" => CompletionState.CompletedWithError,
            _ => throw new ArgumentOutOfRangeException(nameof(completionState), completionState, "Unsupported completion state.")
        };
    }

    private static LogLevel ParseLogLevel(string level)
    {
        return LoggingExports.ParseLogLevel(level, throwOnUnknown: true);
    }
}

View on GitHub (pinned to 25830f84bd)