dotnet/aspnetcore · error · InvalidOperationException

The ComponentRenderMode field only exists on frames of type

Error message

The ComponentRenderMode field only exists on frames of type ComponentRenderMode.

What it means

RenderTreeFrame is a struct with explicit memory layout where multiple frame types share the same field offset (FieldOffset(16)). The ComponentRenderMode property explicitly validates that FrameType equals ComponentRenderMode before returning the field, unlike most other properties that trust the caller. This prevents reading meaningless data when the offset is occupied by a different frame type's data.

Source

Thrown at src/Components/Components/src/RenderTree/RenderTreeFrame.cs:278

    // --------------------------------------------------------------------------------
    // RenderTreeFrameType.ComponentRenderMode
    // --------------------------------------------------------------------------------

    [FieldOffset(16)] internal IComponentRenderMode ComponentRenderModeField;

    /// <summary>
    /// If the <see cref="FrameType"/> property equals <see cref="RenderTreeFrameType.ComponentRenderMode"/>,
    /// gets the specified <see cref="IComponentRenderMode"/>. Otherwise, the value is undefined.
    /// </summary>
    public IComponentRenderMode ComponentRenderMode
    {
        get
        {
            // Normally we don't check the frame type matches, and leave it to the caller to be responsible for only evaluating the correct properties.
            // However the name "ComponentRenderMode" sounds so much like it would be a field on Component frames that we'll explicitly check to avoid mistakes.
            if (FrameType != RenderTreeFrameType.ComponentRenderMode)
            {
                throw new InvalidOperationException($"The {nameof(ComponentRenderMode)} field only exists on frames of type {nameof(RenderTreeFrameType.ComponentRenderMode)}.");
            }

            return ComponentRenderModeField;
        }
    }

    // --------------------------------------------------------------------------------
    // RenderTreeFrameType.NamedEvent
    // --------------------------------------------------------------------------------

    [FieldOffset(16)] internal string NamedEventTypeField;
    [FieldOffset(24)] internal string NamedEventAssignedNameField;

    /// <summary>
    /// If the <see cref="FrameType"/> property equals <see cref="RenderTreeFrameType.NamedEvent"/>,
    /// gets the event type. Otherwise, the value is undefined.
    /// </summary>
    public string NamedEventType => NamedEventTypeField;

View on GitHub (pinned to 294cab2f9b)

Solutions

1. Always check frame.FrameType == RenderTreeFrameType.ComponentRenderMode before accessing frame.ComponentRenderMode.
2. Use a switch on FrameType to dispatch to the correct property accessor for each frame type.
3. If iterating frames in a test, use the RenderTreeFrame collection extension methods that handle type dispatching.
4. Avoid reading frame properties directly unless you have verified the FrameType.

Example fix

// before
foreach (ref var frame in builder.GetFrames())
{
    var mode = frame.ComponentRenderMode; // throws if not ComponentRenderMode
}

// after
foreach (ref var frame in builder.GetFrames())
{
    if (frame.FrameType == RenderTreeFrameType.ComponentRenderMode)
    {
        var mode = frame.ComponentRenderMode;
    }
}

// Always check FrameType before accessing ComponentRenderMode
static IComponentRenderMode? SafeGetComponentRenderMode(ref RenderTreeFrame frame)
    => frame.FrameType == RenderTreeFrameType.ComponentRenderMode
        ? frame.ComponentRenderMode
        : null;

static bool IsComponentRenderModeFrame(ref RenderTreeFrame frame)
    => frame.FrameType == RenderTreeFrameType.ComponentRenderMode;

When it happens

Trigger: Calling frame.ComponentRenderMode on a RenderTreeFrame whose FrameType is not RenderTreeFrameType.ComponentRenderMode. This is an internal API misuse, typically in custom RenderTreeBuilder traversal code or in tests that enumerate frames and access properties without checking FrameType first.

Common situations: Writing custom code that iterates over RenderTreeBuilder frames and accesses properties without first checking FrameType; unit tests inspecting render trees; incorrectly typed frame access in low-level rendering extensions.

Related errors

• The FrameType must be Attribute.
• More than one sibling has the same key value, '{key}'. Key v
• The options parameter is required.
• The custom event '${eventName}' cannot have the same name as
• initialParameters must be an object, even if empty.

AI-assisted analysis of dotnet/aspnetcore@294cab2f9b (2026-08-06). Data as JSON: /api/errors/f0648a5b77b00bba. Report an issue: GitHub.