tui-cs/Terminal.Gui · error · JsonException

{propertyName}: Unexpected Key property.

Error message

{propertyName}: Unexpected Key property.

What it means

Thrown by KeyCodeJsonConverter.Read (KeyCodeJsonConverter.cs:109-110) via the default switch case when a property name inside a Key JSON object is neither "key" nor "modifiers" (compared case-insensitively after ToLowerInvariant). Any unrecognized property in the Key object is rejected.

Source

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

                                        modifiers.Add (modifierDict [mod]);
                                    }
                                    catch (KeyNotFoundException e)
                                    {
                                        throw new JsonException ($"{propertyName}: \"{mod}\" is not a valid modifier.", e);
                                    }
                                }
                            }
                            else
                            {
                                throw new JsonException (
                                                         $"{propertyName}: Expected an array of modifiers, but got \"{reader.TokenType}\"."
                                                        );
                            }

                            break;

                        default:
                            throw new JsonException ($"{propertyName}: Unexpected Key property.");
                    }
                }
            }

            foreach (KeyCode modifier in modifiers)
            {
                key |= modifier;
            }

            return key;
        }

        throw new JsonException ($"{propertyName}: Unexpected StartObject token when parsing Key: {reader.TokenType}.");
    }

    public override void Write (Utf8JsonWriter writer, KeyCode value, JsonSerializerOptions options)
    {
        writer.WriteStartObject ();

View on GitHub (pinned to 2e47b11478)

Solutions

1. Remove the unrecognized property; Key objects only support "Key" and "Modifiers".
2. Check the property name spelling and case — matching is case-insensitive but the names must be 'key' or 'modifiers'.
3. If you need to express additional key metadata, use the Key[] string-array format with Key.TryParse-compatible strings.
4. Regenerate the config from Terminal.Gui to see the exact supported shape.

Example fix

// before
{ "Key": "A", "Modifiers": ["Ctrl"], "Scancode": 30 }

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

using System.Collections.Generic;

static readonly HashSet<string> AllowedKeyProps = new (System.StringComparer.OrdinalIgnoreCase)
{ "Key", "Modifiers" };

static bool KeyObjectHasOnlyAllowedProps (IEnumerable<string> propNames)
    => propNames.All (p => AllowedKeyProps.Contains (p));

// Validate the Key object schema before serializing/deserializing.

static bool IsAllowedKeyProperty (string propName)
    => propName.Equals ("Key", StringComparison.OrdinalIgnoreCase)
       || propName.Equals ("Modifiers", StringComparison.OrdinalIgnoreCase);

try
{
    ConfigurationManager.Load (configJson);
}
catch (JsonException ex) when (ex.Message.Contains ("Unexpected Key property"))
{
    // The Key object has an unknown property. Remove it and reload.
}

When it happens

Trigger: A keybinding JSON object contains an extra/unknown property, e.g. {"Key":"A","Modifiers":["Ctrl"],"Scancode":65} or {"Key":"A","Char":"a"}. The 'default' branch fires for the unrecognized property name.

Common situations: User adds a property (Scancode, Char, CharKey, VirtualKey) thinking the converter supports it. Config schema drift across versions where a property was renamed. Copy-paste from documentation of a different key-serialization format.

Related errors

• {propertyName}: Unexpected StartObject token when parsing Ke
• Expected start of array for Key[].
• Expected string token in Key array, got {reader.TokenType}.
• {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/1194e063ae107136. Report an issue: GitHub.