tui-cs/Terminal.Gui · error · ArgumentException

HotKey does not support CtrlMask ({hotKey}).

Error message

HotKey does not support CtrlMask ({hotKey}).

What it means

HotKey does not support the Ctrl modifier because Ctrl+letter conflicts with terminal control sequences and the application's own command bindings. Only Alt and Shift (for letters A–Z) are auto-applied. Passing a key with Ctrl set is explicitly rejected.

Source

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

        if (_hotKey == hotKey)
        {
            return false;
        }

        Key newKey = hotKey;

        Key baseKey = newKey.NoAlt.NoShift.NoCtrl;

        if (newKey != Key.Empty && Rune.IsControl (baseKey.AsRune))
        {
            throw new ArgumentException (@$"HotKey must be a printable key ({hotKey}).");
        }

        if (newKey != baseKey)
        {
            if (newKey.IsCtrl)
            {
                throw new ArgumentException (@$"HotKey does not support CtrlMask ({hotKey}).");
            }

            // Strip off the shift mask if it's A...Z
            if (baseKey.IsKeyCodeAtoZ)
            {
                newKey = newKey.NoShift;
            }

            // Strip off the Alt mask
            newKey = newKey.NoAlt;
        }

        // Remove base version
        if (HotKeyBindings.TryGet (prevHotKey, out _))
        {
            HotKeyBindings.Remove (prevHotKey);
        }

View on GitHub (pinned to 2e47b11478)

Solutions

1. Strip Ctrl with .NoCtrl before assigning, or use a plain Alt+letter.
2. For Ctrl-based shortcuts, use KeyBindings.Add(key, command) directly.

Example fix

// before
view.HotKey = Key.S.WithCtrl;
// after
view.KeyBindings.Add (Key.S.WithCtrl, Command.Save);

view.HotKey = candidate.IsCtrl ? throw new ArgumentException("no ctrl") : candidate;

static bool HotKeyHasNoCtrl (Key k) => !k.IsCtrl;

When it happens

Trigger: Setting view.HotKey = Key.A.WithCtrl, Key.Q.WithCtrl, or any Key value where IsCtrl is true.

Common situations: Recording a Ctrl+key shortcut and mistakenly assigning it to HotKey; OR-ing Key.CtrlMask into a hot key value.

Related errors

• HotKey must not be null. Use Key.Empty to clear the HotKey.
• HotKey must be a printable key ({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/1ae7ee963e976230. Report an issue: GitHub.