{"record":{"id":"c8346cfbe856bfd6","repo":"tui-cs/Terminal.Gui","slug":"expected-start-of-array-for-key","errorCode":null,"errorMessage":"Expected start of array for Key[].","messagePattern":"Expected start of array for Key\\[\\]\\.","errorType":"exception","errorClass":"JsonException","httpStatus":null,"severity":"error","filePath":"Terminal.Gui/Configuration/KeyArrayJsonConverter.cs","lineNumber":22,"sourceCode":"namespace Terminal.Gui.Configuration;\n\n/// <summary>\n///     Serializes and deserializes <see cref=\"Key\"/> arrays as JSON string arrays (e.g. <c>[\"Ctrl+A\", \"Home\"]</c>).\n///     Each element uses <see cref=\"Key.ToString()\"/> for writing and <see cref=\"Key.TryParse\"/> for reading.\n/// </summary>\npublic class KeyArrayJsonConverter : JsonConverter<Key []?>\n{\n    /// <inheritdoc/>\n    public override Key []? Read (ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)\n    {\n        if (reader.TokenType == JsonTokenType.Null)\n        {\n            return null;\n        }\n\n        if (reader.TokenType != JsonTokenType.StartArray)\n        {\n            throw new JsonException (\"Expected start of array for Key[].\");\n        }\n\n        List<Key> keys = [];\n\n        while (reader.Read ())\n        {\n            if (reader.TokenType == JsonTokenType.EndArray)\n            {\n                return keys.ToArray ();\n            }\n\n            if (reader.TokenType != JsonTokenType.String)\n            {\n                throw new JsonException ($\"Expected string token in Key array, got {reader.TokenType}.\");\n            }\n\n            string keyString = reader.GetString ()!;\n","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/tui-cs/Terminal.Gui/blob/2e47b11478db083499917f2ad27c34d30efb0df1/Terminal.Gui/Configuration/KeyArrayJsonConverter.cs#L4-L40","documentation":"Thrown by KeyArrayJsonConverter.Read (KeyArrayJsonConverter.cs:20-23) when the token is neither Null nor StartArray. Key[] config properties must be JSON string arrays like [\"Ctrl+A\", \"Home\"]. A non-array (object, number, bare string) for a Key[] property produces this JsonException.","triggerScenarios":"A keybinding config JSON has a Key[] property (e.g. a command's bound keys) written as a single string \"Ctrl+A\" or an object instead of an array [\"Ctrl+A\"].","commonSituations":"User writes a single keybinding as \"Accept\": \"Enter\" instead of \"Accept\": [\"Enter\"]. Config migration from a format that uses scalars for single bindings. Copying a keybinding value from elsewhere that omitted the brackets.","solutions":["Wrap the key value(s) in a JSON array even for a single binding: [\"Enter\"].","Use null explicitly if the property should be cleared, since null is accepted (returns null).","Cross-check the format against a serialized sample produced by Terminal.Gui itself.","Validate the config JSON with a schema that enforces array type for Key[] properties."],"exampleFix":"// before\n\"Accept\": \"Enter\"\n\n// after\n\"Accept\": [\"Enter\"]","handlingStrategy":"validation","validationCode":"using System.Text.Json;\n\nstatic bool IsKeyArrayProperty (string json, string propertyName)\n{\n    using JsonDocument doc = JsonDocument.Parse (json);\n    if (!doc.RootElement.TryGetProperty (propertyName, out JsonElement el)) return true;\n    return el.ValueKind == JsonValueKind.Array || el.ValueKind == JsonValueKind.Null;\n}\n\nif (!IsKeyArrayProperty (configJson, \"Accept\"))\n{\n    // wrap the scalar in an array before loading\n}","typeGuard":"static bool IsKeyArray (JsonElement el)\n    => el.ValueKind == JsonValueKind.Array || el.ValueKind == JsonValueKind.Null;","tryCatchPattern":"try\n{\n    ConfigurationManager.Load (configJson);\n}\ncatch (JsonException ex) when (ex.Message.Contains (\"Expected start of array for Key[]\"))\n{\n    // Rewrite the scalar/property to a JSON array [\"...\"] and reload.\n}","preventionTips":["Always wrap Key[] bindings in a JSON array, even single bindings.","Use null to clear a Key[] property (it is accepted).","Validate config with a schema enforcing array type for Key[] properties.","Use a Terminal.Gui-serialized config as the canonical format reference."],"tags":["json","configuration","keybindings","key","serialization"],"backgroundTag":null,"analyzedSha":"2e47b11478db083499917f2ad27c34d30efb0df1","analyzedAt":"2026-08-13T19:20:08.826Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}