dotnet/wpf · error · NotSupportedException

SR.KeyGesture_Invalid (modifiers, key)

Error message

SR.KeyGesture_Invalid (modifiers, key)

What it means

Even with defined Key and ModifierKeys values, KeyGesture throws NotSupportedException with SR.KeyGesture_Invalid when validateGesture is true and IsValid(key, modifiers) fails. WPF requires function keys (F1-F24) or a key paired with a non-None modifier (with limited exceptions like Esc, Del, and other navigation keys which may be standalone). Pure letter/digit keys with no modifier are not valid gestures.

Solutions

  1. Require a modifier for non-function keys: new KeyGesture(Key.A, ModifierKeys.Control)
  2. Use function keys (F1-F12) or valid standalone keys (Esc, Del, etc.) when no modifier is desired
  3. Validate with KeyGesture.IsValid(key, modifiers) before constructing and show a friendly error to users

Example fix

// before
var gesture = new KeyGesture(Key.A); // invalid: no modifier
// after
var gesture = new KeyGesture(Key.A, ModifierKeys.Control);
Defensive patterns

Strategy: validation

Validate before calling

if (!KeyGesture.IsValid(key, modifiers)) throw new ArgumentException("Key+modifier combination is not a valid gesture.");

Type guard

static bool IsConfigurableGesture(Key k, ModifierKeys m) => KeyGesture.IsValid(k, m);

Try / catch

try { var g = new KeyGesture(key, modifiers); } catch (NotSupportedException ex) { /* invalid combination, e.g. bare letter key */ }

Prevention

When it happens

Trigger: new KeyGesture(Key.A) — a letter with no modifiers; new KeyGesture(Key.D1, ModifierKeys.None); similar no-modifier non-function keys via any public constructor.

Common situations: Allowing users to configure a shortcut with just a letter key, or building gestures from parsed strings like 'A' without modifiers.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of dotnet/wpf@81131a70a4 (2026-09-14). Data as JSON: /api/errors/2636c238472e5c9b. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationCore/System/Windows/Input/Command/KeyGesture.cs:100

        /// Private constructor that does the real work.
        /// </summary>
        /// <param name="key">Key</param>
        /// <param name="modifiers">Modifiers</param>
        /// <param name="displayString">display string</param>
        /// <param name="validateGesture">If true, throws an exception if the key and modifier are not valid</param>
        private KeyGesture(Key key, ModifierKeys modifiers, string displayString, bool validateGesture)
        {
            if(!ModifierKeysConverter.IsDefinedModifierKeys(modifiers))
                throw new InvalidEnumArgumentException("modifiers", (int)modifiers, typeof(ModifierKeys));

            if(!IsDefinedKey(key))
                throw new InvalidEnumArgumentException("key", (int)key, typeof(Key));

            ArgumentNullException.ThrowIfNull(displayString);

            if (validateGesture && !IsValid(key, modifiers))
            {
                throw new NotSupportedException(SR.Format(SR.KeyGesture_Invalid, modifiers, key));
            }

            _modifiers = modifiers;
            _key = key;
            _displayString = displayString;
        }
#endregion Constructors

        //------------------------------------------------------
        //
        //  Public Methods
        //
        //------------------------------------------------------
#region Public Methods
        /// <summary>
        /// Modifier
        /// </summary>
        public ModifierKeys Modifiers

View on GitHub (pinned to 81131a70a4)