tui-cs/Terminal.Gui · error · ArgumentException

HotKey must not be null. Use Key.Empty to clear the HotKey.

Error message

HotKey must not be null. Use Key.Empty to clear the HotKey.

What it means

The HotKey property does not accept a null Key. The library distinguishes 'no hot key assigned' (Key.Empty) from 'unset reference' (null) to keep the property non-nullable. Passing null indicates a programming error rather than intent to clear.

Source

Thrown at Terminal.Gui/ViewBase/View.Keyboard.cs:90

    ///         <see cref="AddKeyBindingsForHotKey"/>.
    ///     </para>
    ///     <para>
    ///         By default, when the HotKey is set to <see cref="Key.A"/> through <see cref="Key.Z"/> key bindings will
    ///         be added for both the un-shifted and shifted versions. This means if the HotKey is <see cref="Key.A"/>, key
    ///         bindings for <c>Key.A</c> and <c>Key.A.WithShift</c> will be added. This behavior can be overriden by
    ///         overriding <see cref="AddKeyBindingsForHotKey"/>.
    ///     </para>
    ///     <para>If the hot key is changed, the <see cref="HotKeyChanged"/> event is fired.</para>
    ///     <para>Set to <see cref="Key.Empty"/> to disable the hot key.</para>
    /// </remarks>
    public Key HotKey
    {
        get => _hotKey;
        set
        {
            if (value is null)
            {
                throw new ArgumentException (@"HotKey must not be null. Use Key.Empty to clear the HotKey.", nameof (value));
            }

            if (!AddKeyBindingsForHotKey (_hotKey, value))
            {
                return;
            }

            // This will cause TextFormatter_HotKeyChanged to be called, firing HotKeyChanged
            // BUGBUG: _hotkey should be set BEFORE setting TextFormatter.HotKey
            _hotKey = value;
            TitleTextFormatter.HotKey = value;
        }
    }

    /// <summary>
    ///     Adds key bindings for the specified HotKey. Useful for views that contain multiple items that each have their
    ///     own HotKey such as <see cref="OptionSelector"/>.
    /// </summary>

View on GitHub (pinned to 2e47b11478)

Solutions

1. Use Key.Empty to clear/disable the hot key.
2. Ensure the Key variable is always assigned a concrete Key (e.g. Key.A) before assignment.
3. Enable nullable reference type warnings to catch null Key at compile time.

Example fix

// before
view.HotKey = condition ? Key.Q : null;
// after
view.HotKey = condition ? Key.Q : Key.Empty;

view.HotKey = key ?? Key.Empty;

static Key NonNullHotKey (Key? k) => k ?? Key.Empty;

When it happens

Trigger: Assigning view.HotKey = null; or passing a Key variable that was never initialized (default null because Key is a reference type in v2).

Common situations: C# nullable context disabled or ignored; conditional hot-key assignment where the branch leaves Key as null; deserializing a HotKey from JSON that omits the field.

Related errors

• HotKey must be a printable key ({hotKey}).
• HotKey does not support CtrlMask ({hotKey}).
• OmitClassName is not allowed when Scope is AppSettingsScope
• Provided text is too short to be any known color format.
• The text provided was null or empty.

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