dotnet/aspnetcore · error · InvalidOperationException

Named events may only be added as children of frames of type

Error message

Named events may only be added as children of frames of type Element

What it means

Thrown by RenderTreeBuilder.AddNamedEvent (emitted by the @naming directive / named event feature for exposing element events under a callable name). A named event is attached to an HTML element so the framework can later dispatch to it; therefore the parent must be an Element frame.

Source

Thrown at src/Components/Components/src/Rendering/RenderTreeBuilder.cs:683

    }

    /// <summary>
    /// Assigns a name to an event in the enclosing element.
    /// </summary>
    /// <param name="eventType">The event type, e.g., 'onsubmit'.</param>
    /// <param name="assignedName">The application-assigned name.</param>
    public void AddNamedEvent(string eventType, string assignedName)
    {
        ArgumentNullException.ThrowIfNull(eventType);
        ArgumentException.ThrowIfNullOrEmpty(assignedName);

        // Note that we could trivially extend this to a generic concept of "named values" that exist within the rendertree
        // and are tracked when added, removed, or updated. Currently we don't need that generality, but if we ever do, we
        // can replace RenderTreeFrameType.NamedEvent with RenderTreeFrameType.NamedValue and use it to implement named events.

        if (GetCurrentParentFrameType() != RenderTreeFrameType.Element)
        {
            throw new InvalidOperationException($"Named events may only be added as children of frames of type {RenderTreeFrameType.Element}");
        }

        _entries.AppendNamedEvent(eventType, assignedName);
        _lastNonAttributeFrameType = RenderTreeFrameType.NamedEvent;
    }

    /// <summary>
    /// Appends a frame representing a region of frames.
    /// </summary>
    /// <param name="sequence">An integer that represents the position of the instruction in the source code.</param>
    public void OpenRegion(int sequence)
    {
        // We are entering a new scope, since we track the "duplicate attributes" per
        // element/component we might need to clean them up now.
        if (_hasSeenAddMultipleAttributes)
        {
            var indexOfLastElementOrComponent = _openElementIndices.Peek();
            ProcessDuplicateAttributes(first: indexOfLastElementOrComponent + 1);

View on GitHub (pinned to 294cab2f9b)

Solutions

Place AddNamedEvent / @naming as a direct child of an element opened via OpenElement.
Verify the enclosing frame is an HTML element, not a component or region.
Move the @naming attribute onto the HTML element that owns the event (e.g., the <form> for onsubmit).

Example fix

// before
builder.AddNamedEvent("onsubmit", "myForm");
builder.OpenElement(0, "form");
...
builder.CloseElement();

// after
builder.OpenElement(0, "form");
builder.AddNamedEvent("onsubmit", "myForm");
...
builder.CloseElement();

Defensive patterns

Strategy: validation

Validate before calling

// Track element scope so AddNamedEvent is only called under an element.
int _elDepth = 0;
void Render(RenderTreeBuilder b) {
    b.OpenElement(0, "form"); _elDepth++;
    if (_elDepth > 0) b.AddNamedEvent("onsubmit", "myForm");
    _elDepth--; b.CloseElement();
}

Prevention

Put @naming on the HTML element that owns the event (e.g., <form @naming-submit="myForm">).
Do not apply named events to components or regions.
Use the .razor @naming directive instead of manual AddNamedEvent where possible.

When it happens

Trigger: Calling builder.AddNamedEvent(eventType, assignedName) when GetCurrentParentFrameType() != Element — inside a Component, a Region, or at the root with no parent. In .razor, a @naming placed on a component or outside an element.

Common situations: Applying @naming to a component rather than an HTML element; hand-written RenderFragment that calls AddNamedEvent without an enclosing OpenElement; refactor that changed the enclosing tag from element to component.

Related errors

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