dotnet/aspnetcore · error · InvalidOperationException

The {nameof(ComponentRenderMode)} field only exists on frame

Error message

The {nameof(ComponentRenderMode)} field only exists on frames of type {nameof(RenderTreeFrameType.ComponentRenderMode)}.

What it means

The RenderTreeFrame.ComponentRenderMode property was accessed on a frame whose FrameType is not ComponentRenderMode. Unlike most frame field accessors, this one explicitly validates because the name is easily confused with the Component frame type. Thrown from the getter of RenderTreeFrame.ComponentRenderMode.

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 3600ca084e)

Solutions

1. Guard access with `if (frame.FrameType == RenderTreeFrameType.ComponentRenderMode) ...` before reading the property.
2. Restructure the tree walk to dispatch on FrameType first.
3. If you actually need the render mode declared on a Component frame, read the ComponentRenderMode child frame, not a field on the Component frame.

Example fix

// before
var mode = frame.ComponentRenderMode;

// after
IComponentRenderMode? mode = frame.FrameType == RenderTreeFrameType.ComponentRenderMode
    ? frame.ComponentRenderMode
    : null;

static bool IsComponentRenderModeFrame(in RenderTreeFrame f)
    => f.FrameType == RenderTreeFrameType.ComponentRenderMode;

When it happens

Trigger: Reading frame.ComponentRenderMode on a frame obtained via an index/iteration without first checking frame.FrameType == RenderTreeFrameType.ComponentRenderMode. Tree-walking/diagnostics code that assumes all 'component-ish' frames carry a render mode.

Common situations: Custom render tree visitors/analyzers. Incorrectly porting code that read Component fields and assuming ComponentRenderMode lives on Component frames. Reflecting over frames in a test helper.

Related errors

• Cannot merge mismatching component descriptors: ${JSON.strin
• Only one interactive runtime may enable navigation intercept
• The component type '{componentType}' has a fixed rendermode
• Render mode already set.
• The registered callback {registration.Callback.Method.Name}

AI-assisted analysis of dotnet/aspnetcore@3600ca084e (2026-08-11). Data as JSON: /api/errors/797d64362fafea9b. Report an issue: GitHub.