tui-cs/Terminal.Gui · error · JsonException

{propertyName}: Error parsing Key value: {ioe.Message}

Error message

{propertyName}: Error parsing Key value: {ioe.Message}

What it means

Thrown by KeyCodeJsonConverter.Read (KeyCodeJsonConverter.cs:66-69) when the "Key" property value is a JSON number but reader.GetInt32() throws InvalidOperationException. GetInt32 throws InvalidOperationException when the token, while nominally a Number, cannot be read as an int in the current reader state (e.g. the value is a JSON number encoded as a string token, or the reader is positioned on a property name rather than a value). The inner exception message is surfaced.

Source

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

                                    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);
                                }
                            }

                            break;

                        case "modifiers":
                            if (reader.TokenType == JsonTokenType.StartArray)
                            {
                                while (reader.Read ())
                                {
                                    if (reader.TokenType == JsonTokenType.EndArray)
                                    {
                                        break;
                                    }

View on GitHub (pinned to 2e47b11478)

Solutions

1. If you intend a numeric KeyCode, write it as a bare JSON number: "Key": 65 (no quotes).
2. Prefer the KeyCode enum name string form ("Key": "Enter") over numeric codes for readability and stability across enum renumbering.
3. Ensure no extra reader advancement issues by validating the JSON object is well-formed with a standard parser first.
4. Use the Key[] string-array format for keybindings, which avoids the numeric path entirely.

Example fix

// before (quoted number causes reader state issue)
{ "Key": "65" }

// after (bare number, or better, the enum name)
{ "Key": 65 }
// or
{ "Key": "A" }

using System.Text.Json;

static bool KeyNumberIsBareInt (string json, string propertyName)
{
    using JsonDocument doc = JsonDocument.Parse (json);
    // Walk to the property of interest; this is illustrative.
    return true; // ensure "Key": 65 not "Key": "65"
}

// Prefer: validate the "Key" number token is an unquoted integer in the raw JSON.

static bool IsBareJsonNumber (JsonElement el) => el.ValueKind == JsonValueKind.Number;

try
{
    ConfigurationManager.Load (configJson);
}
catch (JsonException ex) when (ex.Message.Contains ("Error parsing Key value"))
{
    // The "Key" number could not be read as Int32. Unquote it / convert to enum name.
}

When it happens

Trigger: The "Key" property is a number but the Utf8JsonReader cannot yield an Int32 — most commonly because reader.Read() was not advanced onto the value token, or the number is presented as a quoted string "65". The catch wraps it as a JsonException with the propertyName.

Common situations: Config JSON has "Key": "65" (string-quoted number) instead of "Key": 65. A malformed JSON stream where the reader state is inconsistent. Tooling that quotes all values.

Related errors

• Expected start of array for Key[].
• Expected string token in Key array, got {reader.TokenType}.
• {propertyName}: "{reader.GetString ()}" is not a valid Key.
• {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/9cc14fa42a74c93b. Report an issue: GitHub.