tui-cs/Terminal.Gui · error · JsonException

{propertyName}: "{reader.GetString ()}" is not a valid Key.

Error message

{propertyName}: "{reader.GetString ()}" is not a valid Key.

What it means

Thrown by KeyCodeJsonConverter.Read (KeyCodeJsonConverter.cs:53-58) when the "Key" property value is a string that neither Enum.TryParse(KeyCode) nor Enum.TryParse with a trimmed leading 'D'/'d' (for the D0..D9 digit-key enum names) can resolve, and the resulting key is still KeyCode.Null. The string is not a recognized KeyCode enum name.

Source

Thrown at Terminal.Gui/Configuration/KeyCodeJsonConverter.cs:55

                    switch (propertyName!.ToLowerInvariant ())
                    {
                        case "key":
                            if (reader.TokenType == JsonTokenType.String)
                            {
                                if (Enum.TryParse (reader.GetString (), false, out key))
                                {
                                    break;
                                }

                                // The enum uses "D0..D9" for the number keys
                                if (Enum.TryParse (reader.GetString ()!.TrimStart ('D', 'd'), false, out key))
                                {
                                    break;
                                }

                                if (key == KeyCode.Null)
                                {
                                    throw new JsonException (
                                                             $"{propertyName}: \"{reader.GetString ()}\" is not a valid Key."
                                                            );
                                }
                            }
                            else if (reader.TokenType == JsonTokenType.Number)
                            {
                                try
                                {
                                    key = (KeyCode)reader.GetInt32 ();
                                }
                                catch (InvalidOperationException ioe)
                                {
                                    throw new JsonException ($"{propertyName}: Error parsing Key value: {ioe.Message}", ioe);
                                }
                                catch (FormatException ioe)
                                {
                                    throw new JsonException ($"{propertyName}: Error parsing Key value: {ioe.Message}", ioe);
                                }

View on GitHub (pinned to 2e47b11478)

Solutions

1. Use the exact KeyCode enum member name (case-sensitive): "Enter", "Home", "Space", "D0", "F1", etc. Check the KeyCode enum definition for valid names.
2. For digit keys use "D0" through "D9" (the converter also accepts "0".."9" by trimming the D prefix).
3. Put modifiers in the separate "Modifiers" array, not in the "Key" string.
4. For combined keys prefer the Key[] string format ("Ctrl+A") which uses Key.TryParse and is more lenient.
5. If case-insensitivity is needed, use the Key[] array form rather than the object KeyCode form.

Example fix

// before
{ "Key": "enter", "Modifiers": ["Ctrl"] }

// after
{ "Key": "Enter", "Modifiers": ["Ctrl"] }

using Terminal.Gui.Input;

static bool IsValidKeyCodeName (string? name)
{
    if (string.IsNullOrEmpty (name)) return false;
    if (Enum.TryParse<KeyCode> (name, false, out _)) return true;
    // the D0..D9 trim path
    if (Enum.TryParse<KeyCode> (name!.TrimStart ('D', 'd'), false, out _)) return true;
    return false;
}

if (!IsValidKeyCodeName (keyName))
{
    // correct the name before writing config
}

static bool IsValidKeyCodeName (string? name)
    => !string.IsNullOrEmpty (name)
       && (Enum.TryParse<KeyCode> (name, false, out _)
           || Enum.TryParse<KeyCode> (name!.TrimStart ('D', 'd'), false, out _));

try
{
    ConfigurationManager.Load (configJson);
}
catch (JsonException ex) when (ex.Message.Contains ("is not a valid Key"))
{
    // The "Key" string does not match a KeyCode enum name.
    // Replace it with the correct case-sensitive KeyCode name and reload.
}

When it happens

Trigger: A keybinding JSON object has "Key": "<bad>" where <bad> is a typo or a non-enum name (e.g. "Enter2", "CtrlA", "Return" if not in the enum, "Spacebar" instead of "Space"). The converter tried exact enum parse and D-prefix-trimmed parse; both failed.

Common situations: User typos a key name in config. User writes a modifier-combined name in the Key field ("Ctrl+A") instead of using the Modifiers array. User uses a Windows virtual-key name not present in the KeyCode enum. Case sensitivity: the first Enum.TryParse uses caseSensitive=true, so "enter" (lowercase) fails this path — though the D-trim path is also case-sensitive.

Related errors

• Expected start of array for Key[].
• Expected string token in Key array, got {reader.TokenType}.
• {propertyName}: Error parsing Key value: {ioe.Message}
• {propertyName}: "{mod}" is not a valid modifier.
• {propertyName}: Expected an array of modifiers, but got "{re

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