stride3d/stride · error · ArgumentException

There should be 5 words

Error message

There should be 5 words

What it means

RefHeader is the SPIR-V module header wrapper over the 5 mandatory header words (magic number, version, generator, bound, schema). The constructor validates the input span length and throws ArgumentException if it is not exactly 5 words. A wrong length means the buffer passed is not a valid SPIR-V header slice.

Solutions

1. Slice exactly the first 5 ints (first 20 bytes) of the module before constructing RefHeader
2. Check the file is at least 20 bytes and load it as int words (little-endian) not raw bytes
3. Validate the magic number 0x07230203 after construction via IsValidMagic
4. Skip a known container prefix if the file is a SPIR-V container rather than a bare module

Example fix

// before
var header = new RefHeader(words);
// after
if (words.Length != 5)
    throw new ArgumentException($"Expected 5 header words, got {words.Length}");
var header = new RefHeader(words.Slice(0, 5).ToArray());

if (words.Length != 5)
    throw new ArgumentException($"SPIR-V header needs exactly 5 words, got {words.Length}");

bool IsSpirvHeader(ReadOnlySpan<int> w) => w.Length == 5 && w[0] == 0x07230203;

try { var header = new RefHeader(words); }
catch (ArgumentException ex)
{
    logger.LogError(ex, "Not a SPIR-V header slice");
    return null;
}

When it happens

Trigger: Calling new RefHeader(...) with a Span<int> whose Length != 5 — e.g. passing the whole module, an empty span, or a misaligned slice of the code words.

Common situations: Reading a SPIR-V file and slicing the wrong number of leading ints; interpreting the module as bytes instead of 32-bit words; an empty/truncated .spv file (0 or <20 bytes).

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• 64bit integers
• A NodeIndex instance cannot be passed as the value of…
• Argument must be at least 2.
• ArgumentNullException (targetProfiles)
• ArgumentNullException: value

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

Appendix: source

Thrown at sources/shaders/Stride.Shaders.Spirv/Parsing/RefHeader.cs:20

/// <summary>
/// A spirv header parser
/// </summary>
public readonly ref struct RefHeader
{
    internal Span<int> Words { get; init; }
    public uint MagicNumber { get => unchecked((uint)Words[0]); set => Words[0] = unchecked((int)value); }
    public SpirvVersion VersionNumber { get => Words[1]; set => Words[1] = value; }
    public int GeneratorMagicNumber { get => Words[2]; set => Words[2] = value; }
    public int Bound { get => Words[3]; set => Words[3] = value; }
    public int Schema { get => Words[4]; set => Words[4] = value; }

    public string Version => $"{VersionNumber >> 16}.{(VersionNumber >> 8) & 0x00FF}";

    public RefHeader(Span<int> words)
    {
        if (words.Length != 5)
            throw new ArgumentException("There should be 5 words");
        Words = words;
    }

    public bool IsValidMagic => MagicNumber == Specification.MagicNumber;

}

View on GitHub (pinned to 96fad776d2)