tui-cs/Terminal.Gui · error · JsonException

Expected start of array for MouseFlags[].

Error message

Expected start of array for MouseFlags[].

What it means

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.

Source

Thrown at Terminal.Gui/Configuration/MouseFlagsArrayJsonConverter.cs:22

namespace Terminal.Gui.Configuration;

/// <summary>
///     Serializes and deserializes <see cref="MouseFlags"/> arrays as JSON string arrays
///     (e.g. <c>["LeftButtonPressed+Shift", "LeftButtonReleased"]</c>).
/// </summary>
public class MouseFlagsArrayJsonConverter : JsonConverter<MouseFlags []?>
{
    /// <inheritdoc/>
    public override MouseFlags []? Read (ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        if (reader.TokenType == JsonTokenType.Null)
        {
            return null;
        }

        if (reader.TokenType != JsonTokenType.StartArray)
        {
            throw new JsonException ("Expected start of array for MouseFlags[].");
        }

        List<MouseFlags> mouseFlagsList = [];

        while (reader.Read ())
        {
            if (reader.TokenType == JsonTokenType.EndArray)
            {
                return mouseFlagsList.ToArray ();
            }

            if (reader.TokenType != JsonTokenType.String)
            {
                throw new JsonException ($"Expected string token in MouseFlags array, got {reader.TokenType}.");
            }

            string mouseFlagsString = reader.GetString ()!;
            mouseFlagsString = mouseFlagsString.Replace ("+", ", ").Replace ("|", ", ");

View on GitHub (pinned to 2e47b11478)

Solutions

1. Wrap mouse-flag values in a JSON array even for a single flag: ["Button1Clicked"].
2. Use null explicitly to clear the property (accepted, returns null).
3. Cross-check against a Terminal.Gui-serialized sample for the canonical format.
4. Validate the property is an array type in the config schema.

Example fix

// before
"Click": "Button1Clicked"

// after
"Click": ["Button1Clicked"]

using System.Text.Json;

static bool IsMouseFlagsArrayProperty (string json, string propertyName)
{
    using JsonDocument doc = JsonDocument.Parse (json);
    if (!doc.RootElement.TryGetProperty (propertyName, out JsonElement el)) return true;
    return el.ValueKind == JsonValueKind.Array || el.ValueKind == JsonValueKind.Null;
}

if (!IsMouseFlagsArrayProperty (configJson, "Click"))
{
    // wrap the scalar in an array before loading
}

static bool IsMouseFlagsArray (JsonElement el)
    => el.ValueKind == JsonValueKind.Array || el.ValueKind == JsonValueKind.Null;

try
{
    ConfigurationManager.Load (configJson);
}
catch (JsonException ex) when (ex.Message.Contains ("Expected start of array for MouseFlags[]"))
{
    // Rewrite the scalar to a JSON array ["..."] and reload.
}

When it happens

Trigger: A mouse-binding config JSON has a MouseFlags[] property written as a single string "Button1Clicked" or an object instead of an array ["Button1Clicked"].

Common situations: User writes a single mouse flag as a scalar for brevity. Tooling collapses single-element arrays. Copy-paste from a format using scalars.

Related errors

• Expected string token in MouseFlags array, got {reader.Token
• Unexpected end of JSON while reading MouseFlags array.
• Expected a JSON array ("[ { ... } ]"), but got "{reader.Toke
• Expected start of array for Key[].
• Expected string token in Key array, got {reader.TokenType}.

AI-assisted analysis of tui-cs/Terminal.Gui@2e47b11478 (2026-08-13). Data as JSON: /api/errors/559fd6874d4f4bec. Report an issue: GitHub.