tui-cs/Terminal.Gui · error · InvalidOperationException

Popovers must be registered before being shown.

Error message

Popovers must be registered before being shown.

What it means

Thrown by ApplicationPopover.Show when the passed IPopoverView is not in the registered popover set. Popovers must first be registered via Register (or Popovers.Register) so the application can track them for keyboard dispatch and lifecycle. Calling Show directly on an unregistered view bypasses that tracking, so the library refuses.

Source

Thrown at Terminal.Gui/App/ApplicationPopover.cs:184

    }

    /// <summary>
    ///     Shows <paramref name="popover"/>. IPopoverView implementations should use OnVisibleChanaged/VisibleChanged to be
    ///     notified when the user has done something to cause the popover to be hidden.
    /// </summary>
    /// <remarks>
    ///     <para>
    ///         This API calls <see cref="Register"/>. To disable the popover from processing keyboard events,
    ///         either call <see cref="DeRegister"/> to
    ///         remove the popover from the application or set <see cref="IPopoverView.Enabled"/> to <see langword="false"/>.
    ///     </para>
    /// </remarks>
    /// <param name="popover"></param>
    public void Show (IPopoverView? popover)
    {
        if (!IsRegistered (popover))
        {
            throw new InvalidOperationException (@"Popovers must be registered before being shown.");
        }

        // Prevent re-show of a popover that was just dismissed by a mouse-press-outside event.
        // The dismiss logic in ApplicationMouse.RaiseMouseEvent sets DismissedByMousePress before recursing,
        // and the guard spans the entire press → release → click cycle. This prevents views beneath
        // the popover from re-opening the same popover during the click that dismissed it.
        if (popover is { } && App?.Mouse is ApplicationMouse { DismissedByMousePress: { } dismissed } && dismissed == popover)
        {
            return;
        }

        // If there's an existing popover, hide it.
        if (_activePopover is { })
        {
            _activePopover.Visible = false;
            _activePopover = null;
        }

View on GitHub (pinned to 2e47b11478)

Solutions

1. Register the popover once before showing: app.Popovers.Register(myPopover); then app.Popovers.Show(myPopover);.
2. Reuse the same registered popover instance across show/hide cycles rather than creating new ones.
3. If the popover may already be registered, guard with IsRegistered before calling Show.

Example fix

// before
var menu = new PopoverMenu (...);
app.Popovers.Show (menu); // throws — not registered

// after
app.Popovers.Register (menu);
app.Popovers.Show (menu);

if (!app.Popovers.IsRegistered (popover))
{
    app.Popovers.Register (popover);
}
app.Popovers.Show (popover);

static bool IsPopoverRegistered (ApplicationPopover p, IPopoverView v) => p.IsRegistered (v);

When it happens

Trigger: Constructing a popover view and calling app.Popovers.Show(view) without a prior app.Popovers.Register(view) call; using a fresh popover instance each time instead of reusing the registered one.

Common situations: Ad-hoc context-menu or tooltip code that builds a new Popover each invocation; copy-pasting a snippet that omits the Register step; assuming Show auto-registers (it does not, despite the XML remark referencing Register).

Related errors

• Init called multiple times without Shutdown
• Cannot use legacy static Application model (Application.Init
• Cannot use modern instance-based model (Application.Create)
• Invoke
• The runnable is already running.

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