microsoft/aspire · error · ArgumentException

A validation message must be provided for a failed…

Error message

A validation message must be provided for a failed validation.

What it means

RequiredCommandValidationResult carries the outcome of a required-command validation: IsValid plus an optional ValidationMessage. The private constructor enforces the invariant that a failed validation must always include a human-readable message, throwing ArgumentException when isValid is false and validationMessage is null. This guarantees the dashboard/interaction UI always has something to show the user when a required command is missing or fails.

Solutions

Always pass a non-null message when creating a failed validation result, e.g. return RequiredCommandValidationResult.Fail("dotnet ef was not found on PATH.");
If the message is computed, coalesce it: var msg = computedMessage ?? "Required command validation failed.";
If the command actually validated fine, create the success result (isValid: true) instead, which permits a null message.

Example fix

// before
return RequiredCommandValidationResult.Fail(missingCommandError); // missingCommandError is null
// after
return RequiredCommandValidationResult.Fail($"Required command '{commandName}' failed validation: {missingCommandError ?? "not found"}");

Defensive patterns

Strategy: validation

Validate before calling

if (!isValid && string.IsNullOrEmpty(validationMessage))
{
    validationMessage = "Required command validation failed."; // supply default before constructing result
}

Type guard

bool IsValidFailure(RequiredCommandValidationResult r) => r is { IsValid: true } || r.ValidationMessage is not null;

Try / catch

try
{
    var result = RequiredCommandValidationResult.Fail(message);
}
catch (ArgumentException ex) when (ex.ParamName == "validationMessage")
{
    result = RequiredCommandValidationResult.Fail("Required command validation failed.");
}

Prevention

Coalesce computed messages with a default string before calling Fail.
Use the factory methods rather than the private constructor so the invariant is checked in one place.
Only pass null messages for successful (isValid: true) results.

When it happens

Trigger: Creating an instance via its factory methods (e.g. RequiredCommandValidationResult.Fail(null) or the private constructor with isValid:false and validationMessage:null) — calling the failure factory without a message.

Common situations: Custom ValidateRequiredCommand implementations that build the failure message in a variable which ends up null (e.g. a lookup of the command's error text returned null); passing an uninitialized string field to Fail/invalid-result factory methods.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/ApplicationModel/RequiredCommandValidationResult.cs:19

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System.Diagnostics.CodeAnalysis;

namespace Aspire.Hosting.ApplicationModel;

/// <summary>
/// Represents the result of validating a required command.
/// </summary>
[Experimental("ASPIRECOMMAND001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
[AspireExport(ExposeProperties = true)]
public sealed class RequiredCommandValidationResult
{
    private RequiredCommandValidationResult(bool isValid, string? validationMessage)
    {
        if (!isValid && validationMessage is null)
        {
            throw new ArgumentException("A validation message must be provided for a failed validation.", nameof(validationMessage));
        }

        IsValid = isValid;
        ValidationMessage = validationMessage;
    }

    /// <summary>
    /// Gets a value indicating whether the command validation succeeded.
    /// </summary>
    [MemberNotNullWhen(false, nameof(ValidationMessage))]
    public bool IsValid { get; }

    /// <summary>
    /// Gets an optional validation message describing why validation failed.
    /// </summary>
    public string? ValidationMessage { get; }

    /// <summary>

View on GitHub (pinned to 25830f84bd)