{"record":{"id":"d9ec24fc8fd1dcd4","repo":"tui-cs/Terminal.Gui","slug":"expected-string-token-in-key-array-got-reader-to","errorCode":null,"errorMessage":"Expected string token in Key array, got {reader.TokenType}.","messagePattern":"Expected string token in Key array, got (.+?)\\.","errorType":"exception","errorClass":"JsonException","httpStatus":null,"severity":"error","filePath":"Terminal.Gui/Configuration/KeyArrayJsonConverter.cs","lineNumber":36,"sourceCode":"        }\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\n            keys.Add (Key.TryParse (keyString, out Key key) ? key : Key.Empty);\n        }\n\n        throw new JsonException (\"Unexpected end of JSON while reading Key array.\");\n    }\n\n    /// <inheritdoc/>\n    public override void Write (Utf8JsonWriter writer, Key []? value, JsonSerializerOptions options)\n    {\n        if (value is null)\n        {\n            writer.WriteNullValue ();\n\n            return;","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/tui-cs/Terminal.Gui/blob/2e47b11478db083499917f2ad27c34d30efb0df1/Terminal.Gui/Configuration/KeyArrayJsonConverter.cs#L18-L54","documentation":"Thrown by KeyArrayJsonConverter.Read (KeyArrayJsonConverter.cs:34-37) inside the array loop when an element token is not a String. Each element of a Key[] JSON array must be a string parseable by Key.TryParse (e.g. \"Ctrl+A\", \"Home\", \"F1\"). A number, boolean, object, or nested array element triggers this.","triggerScenarios":"A Key[] JSON array contains a non-string element, e.g. [\"Ctrl+A\", 65] (numeric keyCode) or [\"Home\", {\"Key\":\"End\"}].","commonSituations":"User writes a numeric key code directly into the array expecting it to be parsed as a KeyCode. A tool emits typed values (numbers) instead of strings. Mixing the Key[] string format with the KeyCodeJsonConverter object format in the same array.","solutions":["Make every element a string token: use the Key.ToString() form (e.g. \"Ctrl+A\", \"D0\", \"F1\") for each entry.","If you have numeric key codes, convert them to their KeyCode enum name strings before writing the config.","Do not mix object-form Key entries (that is the KeyCodeJsonConverter format) into a Key[] array.","Validate each array element is a JSON string before serializing."],"exampleFix":"// before\n\"Accept\": [\"Ctrl+A\", 13]\n\n// after\n\"Accept\": [\"Ctrl+A\", \"Enter\"]","handlingStrategy":"validation","validationCode":"using System.Text.Json;\n\nstatic bool KeyArrayElementsAreStrings (string json, string propertyName)\n{\n    using JsonDocument doc = JsonDocument.Parse (json);\n    if (!doc.RootElement.TryGetProperty (propertyName, out JsonElement el)) return true;\n    if (el.ValueKind != JsonValueKind.Array) return false;\n    foreach (JsonElement item in el.EnumerateArray ())\n    {\n        if (item.ValueKind != JsonValueKind.String) return false;\n    }\n    return true;\n}","typeGuard":"static bool IsKeyArrayElement (JsonElement el) => el.ValueKind == JsonValueKind.String;","tryCatchPattern":"try\n{\n    ConfigurationManager.Load (configJson);\n}\ncatch (JsonException ex) when (ex.Message.Contains (\"Expected string token in Key array\"))\n{\n    // Find the non-string element and replace it with its Key.ToString() form.\n}","preventionTips":["Write every Key[] element as a string in Key.ToString() form (e.g. \"Ctrl+A\", \"Home\", \"F1\").","Convert numeric key codes to KeyCode enum names before writing config.","Do not mix object-form Key entries into a Key[] array.","Validate each array element is a string before serializing."],"tags":["json","configuration","keybindings","key","serialization"],"backgroundTag":null,"analyzedSha":"2e47b11478db083499917f2ad27c34d30efb0df1","analyzedAt":"2026-08-13T19:20:08.826Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}