{"record":{"id":"559fd6874d4f4bec","repo":"tui-cs/Terminal.Gui","slug":"expected-start-of-array-for-mouseflags","errorCode":null,"errorMessage":"Expected start of array for MouseFlags[].","messagePattern":"Expected start of array for MouseFlags\\[\\]\\.","errorType":"exception","errorClass":"JsonException","httpStatus":null,"severity":"error","filePath":"Terminal.Gui/Configuration/MouseFlagsArrayJsonConverter.cs","lineNumber":22,"sourceCode":"namespace Terminal.Gui.Configuration;\n\n/// <summary>\n///     Serializes and deserializes <see cref=\"MouseFlags\"/> arrays as JSON string arrays\n///     (e.g. <c>[\"LeftButtonPressed+Shift\", \"LeftButtonReleased\"]</c>).\n/// </summary>\npublic class MouseFlagsArrayJsonConverter : JsonConverter<MouseFlags []?>\n{\n    /// <inheritdoc/>\n    public override MouseFlags []? 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 MouseFlags[].\");\n        }\n\n        List<MouseFlags> mouseFlagsList = [];\n\n        while (reader.Read ())\n        {\n            if (reader.TokenType == JsonTokenType.EndArray)\n            {\n                return mouseFlagsList.ToArray ();\n            }\n\n            if (reader.TokenType != JsonTokenType.String)\n            {\n                throw new JsonException ($\"Expected string token in MouseFlags array, got {reader.TokenType}.\");\n            }\n\n            string mouseFlagsString = reader.GetString ()!;\n            mouseFlagsString = mouseFlagsString.Replace (\"+\", \", \").Replace (\"|\", \", \");","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/tui-cs/Terminal.Gui/blob/2e47b11478db083499917f2ad27c34d30efb0df1/Terminal.Gui/Configuration/MouseFlagsArrayJsonConverter.cs#L4-L40","documentation":"Thrown by MouseFlagsArrayJsonConverter.Read (MouseFlagsArrayJsonConverter.cs:20-23) when the token is neither Null nor StartArray. MouseFlags[] config properties must be JSON string arrays like [\"Button1Clicked\", \"Button1Clicked+Shift\"]. A non-array value (object, number, bare string) triggers this JsonException.","triggerScenarios":"A mouse-binding config JSON has a MouseFlags[] property written as a single string \"Button1Clicked\" or an object instead of an array [\"Button1Clicked\"].","commonSituations":"User writes a single mouse flag as a scalar for brevity. Tooling collapses single-element arrays. Copy-paste from a format using scalars.","solutions":["Wrap mouse-flag values in a JSON array even for a single flag: [\"Button1Clicked\"].","Use null explicitly to clear the property (accepted, returns null).","Cross-check against a Terminal.Gui-serialized sample for the canonical format.","Validate the property is an array type in the config schema."],"exampleFix":"// before\n\"Click\": \"Button1Clicked\"\n\n// after\n\"Click\": [\"Button1Clicked\"]","handlingStrategy":"validation","validationCode":"using System.Text.Json;\n\nstatic bool IsMouseFlagsArrayProperty (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 (!IsMouseFlagsArrayProperty (configJson, \"Click\"))\n{\n    // wrap the scalar in an array before loading\n}","typeGuard":"static bool IsMouseFlagsArray (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 MouseFlags[]\"))\n{\n    // Rewrite the scalar to a JSON array [\"...\"] and reload.\n}","preventionTips":["Always wrap MouseFlags[] bindings in a JSON array, even single bindings.","Use null to clear a MouseFlags[] property (accepted).","Validate config with a schema enforcing array type for MouseFlags[] properties.","Use a Terminal.Gui-serialized config as the canonical format reference."],"tags":["json","configuration","mouse","mousebindings","serialization"],"backgroundTag":null,"analyzedSha":"2e47b11478db083499917f2ad27c34d30efb0df1","analyzedAt":"2026-08-13T19:20:08.826Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}