tui-cs/Terminal.Gui · error · InvalidOperationException

Adornment must be of type Border

Error message

Adornment must be of type Border

What it means

This error is thrown by BorderView.OnDrawingContent() when the Adornment associated with the BorderView is not of type Border. BorderView is a specialized AdornmentView whose rendering logic (DrawTabBorder, DrawLegacyBorder) assumes its Adornment is specifically a Border, not a generic Margin or Padding. This invariant is established during view construction and should never be violated in normal use; hitting it indicates a programming error in view construction or adornment assignment.

Source

Thrown at Terminal.Gui/ViewBase/Adornment/BorderView.cs:219

                              Math.Max (0,
                                        screenRect.Width
                                        - Math.Max (0, Math.Max (0, Adornment.Thickness.Left - 1) + Math.Max (0, Adornment.Thickness.Right - 1))),
                              Math.Max (0,
                                        screenRect.Height
                                        - Math.Max (0, Math.Max (0, Adornment.Thickness.Top - 1) + Math.Max (0, Adornment.Thickness.Bottom - 1))));
    }

    /// <inheritdoc/>
    protected override bool OnDrawingContent (DrawContext? context)
    {
        if (Adornment is null || Adornment.Thickness == Thickness.Empty)
        {
            return true;
        }

        if (Adornment is not Border border)
        {
            throw new InvalidOperationException ("Adornment must be of type Border");
        }

        // Tab mode: completely separate codepath with edge-based border positioning
        if (border.Settings.FastHasFlags (BorderSettings.Tab))
        {
            return DrawTabBorder (border);
        }

        return DrawLegacyBorder (context, border);
    }

    /// <summary>
    ///     INTERNAL: Draws the border and title when <see cref="BorderSettings.Tab"/> is not set.
    ///     Retained for backward compatibility and for use when tab mode is not desired.
    /// </summary>
    private bool DrawLegacyBorder (DrawContext? context, Border border)
    {
        Rectangle screenBounds = ViewportToScreen (Viewport);

View on GitHub (pinned to 2e47b11478)

Solutions

1. Ensure BorderView is only used with Border adornments -- this is enforced by the normal View API; do not bypass it.
2. If subclassing, preserve the Border type constraint on the Adornment property.
3. If using reflection or test tooling to manipulate adornments, verify type compatibility before assignment.
4. Check for any code that creates a BorderView and manually sets its Adornment to a non-Border adornment.

Example fix

// before -- assigning wrong adornment type to BorderView
borderView.GetType().GetProperty("Adornment").SetValue(borderView, new Margin(...));

// after -- BorderView only works with Border
view.Border = new Border { Thickness = new Thickness(1) };
// The BorderView is created internally and correctly associated

// Ensure BorderView is only used with Border adornments
if (adornment is Border) { /* safe to use with BorderView */ }

bool IsValidBorderAdornment(Adornment a) => a is Border;

// OnDrawingContent is called internally; no caller-side catch is typical.
// This indicates a construction bug -- fix the adornment assignment.

When it happens

Trigger: Thrown at BorderView.cs:219 when OnDrawingContent is called and Adornment is not null, has non-empty Thickness, but is not castable to Border. This implies a BorderView was associated with the wrong type of adornment, which should be structurally impossible through normal API usage.

Common situations: Custom view construction code that manually assigns the wrong adornment type to a BorderView, reflection-based test tooling that reassigns adornments, subclassing AdornmentView/BorderView incorrectly, or internal bugs during view composition.

Related errors

• AdornmentView can only render to their Parent or Parent's Su
• The Viewport of an AdornmentView cannot be modified.
• The ShadowStyle of MarginView cannot be set
• Target
• Cannot change timeout while mouse is held down. Call Stop()

AI-assisted analysis of tui-cs/Terminal.Gui@2e47b11478 (2026-08-13). Data as JSON: /api/errors/783ea0b95b21db7a. Report an issue: GitHub.