tui-cs/Terminal.Gui · error · JsonException

Expected string token in MouseFlags array, got {reader.Token

Error message

Expected string token in MouseFlags array, got {reader.TokenType}.

What it means

Thrown by MouseFlagsArrayJsonConverter.Read (MouseFlagsArrayJsonConverter.cs:34-37) inside the array loop when an element token is not a String. Each element of a MouseFlags[] JSON array must be a string parseable as MouseFlags (with '+' or '|' split into combined flags). A number, boolean, object, or nested array element triggers this.

Source

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

        }

        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 ("|", ", ");

            mouseFlagsList.Add (Enum.TryParse (mouseFlagsString, true, out MouseFlags mouseFlags) ? mouseFlags : MouseFlags.None);
        }

        throw new JsonException ("Unexpected end of JSON while reading MouseFlags array.");
    }

    /// <inheritdoc/>
    public override void Write (Utf8JsonWriter writer, MouseFlags []? value, JsonSerializerOptions options)
    {
        if (value is null)
        {
            writer.WriteNullValue ();

View on GitHub (pinned to 2e47b11478)

Solutions

1. Make every element a string token using MouseFlags enum names: "Button1Clicked", "WheeledUp", "Button1Clicked+Shift", etc.
2. Combine flags with '+' or '|' inside the string: "Button1Clicked+Shift" is accepted (the converter splits on '+' and '|').
3. Convert any numeric flag values to their MouseFlags enum name strings before writing config.
4. Validate each array element is a JSON string.

Example fix

// before
"Click": ["Button1Clicked", 0x100000]

// after
"Click": ["Button1Clicked", "Button1Clicked+Shift"]

using System.Text.Json;

static bool MouseFlagsElementsAreStrings (string json, string propertyName)
{
    using JsonDocument doc = JsonDocument.Parse (json);
    if (!doc.RootElement.TryGetProperty (propertyName, out JsonElement el)) return true;
    if (el.ValueKind != JsonValueKind.Array) return false;
    foreach (JsonElement item in el.EnumerateArray ())
    {
        if (item.ValueKind != JsonValueKind.String) return false;
    }
    return true;
}

static bool IsMouseFlagsArrayElement (JsonElement el) => el.ValueKind == JsonValueKind.String;

try
{
    ConfigurationManager.Load (configJson);
}
catch (JsonException ex) when (ex.Message.Contains ("Expected string token in MouseFlags array"))
{
    // Find the non-string element and replace it with its MouseFlags.ToString() form.
}

When it happens

Trigger: A MouseFlags[] JSON array contains a non-string element, e.g. ["Button1Clicked", 1] (numeric flag value) or ["Button1Clicked", {"Flags":"Button2Clicked"}].

Common situations: User writes a numeric MouseFlags enum value directly. Tooling emits typed numbers. Mixing formats.

Related errors

• Expected start of array for MouseFlags[].
• 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/36e8c651fc76614d. Report an issue: GitHub.