tui-cs/Terminal.Gui · error · ArgumentException

Invalid key string: {str}

Error message

Invalid key string: {str}

What it means

This error is thrown by the Key(string) constructor when the provided string cannot be parsed into a valid Key via TryParse. The Key class represents keyboard keys, and its string constructor is used to create Key instances from textual descriptions like 'Ctrl+C', 'Alt+F4', or 'Shift+Up'. If the string does not match the expected format documented in TryParse, an ArgumentException is thrown.

Source

Thrown at Terminal.Gui/Input/Keyboard/Key.cs:147

            default:
                KeyCode = (KeyCode)ch;

                break;
        }
    }

    /// <summary>
    ///     Constructs a new Key from a string describing the key. See
    ///     <see cref="TryParse(string, out Key)"/> for information on the format of the string.
    /// </summary>
    /// <param name="str">The string describing the key.</param>
    public Key (string str)
    {
        bool result = TryParse (str, out Key key);

        if (!result)
        {
            throw new ArgumentException (@$"Invalid key string: {str}", nameof (str));
        }

        KeyCode = key.KeyCode;
    }

    /// <summary>
    ///     Constructs a new Key from an integer describing the key.
    ///     It parses the integer as Key by calling the constructor with a char or calls the constructor with a
    ///     KeyCode.
    /// </summary>
    /// <remarks>
    ///     Don't rely on <paramref name="value"/> passed from <see cref="KeyCode.A"/> to <see cref="KeyCode.Z"/> because
    ///     would not return the expected keys from 'a' to 'z'.
    /// </remarks>
    /// <param name="value">The integer describing the key.</param>
    /// <exception cref="ArgumentOutOfRangeException"></exception>
    /// <exception cref="ArgumentException"></exception>
    public Key (int value)

View on GitHub (pinned to 2e47b11478)

Solutions

1. Check the key string format against the TryParse documentation -- modifiers are 'Ctrl', 'Alt', 'Shift' joined with '+', followed by a key name or character.
2. Use Key.TryParse(str, out Key key) instead of the constructor to handle invalid input gracefully.
3. Correct the typo or malformed key string in the configuration.
4. Validate configuration key strings at load time rather than at binding registration.

Example fix

// before -- invalid key string throws ArgumentException
Key key = new Key("Controll+C");

// after -- use TryParse to handle invalid strings
if (!Key.TryParse("Ctrl+C", out Key key)) { Console.Error.WriteLine("Invalid key binding string."); }

string keyStr = "Ctrl+C";
if (Key.TryParse(keyStr, out Key key)) { /* use key */ }
else { Console.Error.WriteLine($"Invalid key string: {keyStr}"); }

try { Key key = new Key(keyStr); }
catch (ArgumentException ex) { Console.Error.WriteLine($"Bad key binding: {ex.Message}"); /* use default key */ }

When it happens

Trigger: Thrown at Key.cs:147 when Key.TryParse(str, out Key key) returns false. The string format must follow the documented grammar: optional modifiers (Ctrl, Alt, Shift) separated by '+', followed by a recognized key name or single character. Invalid formats, unknown key names, or malformed modifier syntax cause TryParse to fail.

Common situations: Loading key bindings from configuration files with typos (e.g., 'Controll+C' instead of 'Ctrl+C'), using unlocalized or undocumented key names, parsing user input that does not match the key grammar, or configuration migration from a different keybinding scheme.

Related errors

• Expected start of array for Key[].
• Expected string token in Key array, got {reader.TokenType}.
• Unexpected end of JSON while reading Key array.
• {propertyName}: "{reader.GetString ()}" is not a valid Key.
• {propertyName}: Error parsing Key value: {ioe.Message}

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