stride3d/stride · error · ArgumentException

Unknown optional qualifier

Error message

Unknown optional qualifier: {str}

What it means

IntrinsicsDefinitions.FromStringOptional parses optional matrix-layout qualifiers into the OptionalQualifier enum. Only 'row_major' and 'col_major' are accepted; anything else throws ArgumentException('Unknown optional qualifier: ...').

Solutions

1. Normalize the input to exactly 'row_major' or 'col_major' (Trim/lowercase, and translate HLSL 'column_major' to 'col_major').
2. If the qualifier is genuinely optional and absent, pass null instead of an empty string (the Parameter.OptionalQualifier field is nullable).
3. If a new optional qualifier is needed, add an arm to the FromStringOptional switch in IntrinsicsParameters.cs.

Example fix

// before
var oq = IntrinsicsDefinitions.FromStringOptional("column_major"); // ArgumentException

// after
var normalized = token == "column_major" ? "col_major" : token.Trim();
var oq = string.IsNullOrEmpty(normalized) ? null : IntrinsicsDefinitions.FromStringOptional(normalized);

var t = token?.Trim();
if (t == "column_major") t = "col_major"; // normalize HLSL spelling
if (t is not ("row_major" or "col_major"))
    return null; // or throw: not a valid optional qualifier

bool IsValidOptionalQualifier(string? s) => s is "row_major" or "col_major";

try { optQualifier = IntrinsicsDefinitions.FromStringOptional(token); }
catch (ArgumentException ex) when (ex.Message.StartsWith("Unknown optional qualifier:"))
{
    optQualifier = null; // qualifier is optional; treat unknown/empty as absent and log
    logger.LogWarning("Ignoring unrecognized optional qualifier '{Token}'", token);
}

When it happens

Trigger: Calling FromStringOptional (directly or while deserializing intrinsic parameter tables) with any string other than 'row_major'/'col_major' — e.g. 'column_major' (HLSL spelling vs the parser's 'col_major'), empty string when the column is absent, or 'packoffset' mistakenly routed to the qualifier field.

Common situations: Porting HLSL intrinsic signatures verbatim ('column_major' instead of 'col_major'); blank table cells being passed as empty strings; typos like 'row-major'; adding a new layout qualifier to the enum without extending the switch.

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

• Unknown qualifier
• Unknown base type
• Could not find dependency
• Unexpected arguments
• Unable to load the given stream

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/c4bcd780e7221a7c. Report an issue: GitHub.

Appendix: source

Thrown at sources/shaders/Stride.Shaders.Parsers/Core/IntrinsicsParameters.cs:106

    { }
}


public static partial class IntrinsicsDefinitions
{
    static Qualifier FromString(string str) => str switch
    {
        "in" => Qualifier.In,
        "out" => Qualifier.Out,
        "inout" => Qualifier.InOut,
        "ref" => Qualifier.Ref,
        _ => throw new ArgumentException($"Unknown qualifier: {str}"),
    };
    static OptionalQualifier FromStringOptional(string str) => str switch
    {
        "row_major" => OptionalQualifier.RowMajor,
        "col_major" => OptionalQualifier.ColumnMajor,
        _ => throw new ArgumentException($"Unknown optional qualifier: {str}"),
    };
}

public enum BaseType
{
    Bool,
    Int,
    Int32Only,
    Int16,
    Int64,
    SInt16Or32,
    AnyInt,
    AnyInt16Or32,
    AnyInt32,
    AnyInt64,
    Int64Only,
    Uint,
    Uint16,

View on GitHub (pinned to 96fad776d2)