tui-cs/Terminal.Gui · error · JsonException

Unexpected token type for TraceCategory: {reader.TokenType}

Error message

Unexpected token type for TraceCategory: {reader.TokenType}

What it means

Thrown by TraceCategoryJsonConverter.Read when the JSON token for a TraceCategory value is not Number, String, or StartArray. TraceCategory accepts three shapes: an integer (6), a single string ("Command"), or an array of strings (["Command","Mouse"]); anything else (true, false, null, StartObject) is rejected at the top level.

Source

Thrown at Terminal.Gui/Configuration/TraceCategoryJsonConverter.cs:64

                {
                    throw new JsonException ($"Unexpected token type in TraceCategory array: {reader.TokenType}");
                }
                string value = reader.GetString ()!;

                if (Enum.TryParse (value, true, out TraceCategory category))
                {
                    result |= category;
                }
                else
                {
                    throw new JsonException ($"Invalid TraceCategory value in array: '{value}'");
                }
            }

            return result;
        }

        throw new JsonException ($"Unexpected token type for TraceCategory: {reader.TokenType}");
    }

    public override void Write (Utf8JsonWriter writer, TraceCategory value, JsonSerializerOptions options)
    {
        if (value == TraceCategory.None)
        {
            writer.WriteStringValue ("None");

            return;
        }

        if (value == TraceCategory.All)
        {
            writer.WriteStringValue ("All");

            return;
        }

View on GitHub (pinned to 2e47b11478)

Solutions

Use one of the three supported forms: integer, single member-name string, or array of member-name strings.
If you want 'no tracing', use the string "None" or the integer 0.
Validate the JSON kind with jq (jq type .config.json) before loading.

Example fix

// before
"TraceCategory": true
// after
"TraceCategory": "None"

Defensive patterns

Strategy: validation

Validate before calling

// Confirm the token kind is one of the three supported shapes
bool IsValidTraceCategoryToken (JsonElement el)
    => el.ValueKind == JsonValueKind.Number
    || el.ValueKind == JsonValueKind.String
    || el.ValueKind == JsonValueKind.Array;

Type guard

static bool IsValidTraceCategoryElement (JsonElement el)
    => el.ValueKind is JsonValueKind.Number or JsonValueKind.String or JsonValueKind.Array;

Try / catch

ConfigurationManager.ThrowOnJsonErrors = false;

Prevention

Use only number, single string, or string array for TraceCategory.
Avoid UI editors that write booleans for enum-like settings.
Use "None" for the off state instead of false/null.

When it happens

Trigger: Putting a JSON boolean, null literal, or nested object where a TraceCategory is expected — e.g. "TraceCategory": true, "TraceCategory": null, or "TraceCategory": { }.

Common situations: A config generator emits the wrong JSON kind; a user toggles a flag in a GUI editor that writes true/false; misunderstanding the schema.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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