What causes "Invalid TraceCategory value: '{value}'" in tui-cs/Terminal.Gui?

Use a valid TraceCategory enum name (check the enum definition in Tracing/TraceCategory.cs for the current members).

tui-cs/Terminal.Gui · error · JsonException

Invalid TraceCategory value: '{value}'

Error message

Invalid TraceCategory value: '{value}'

What it means

Thrown by TraceCategoryJsonConverter.Read when the JSON token is a single string but Enum.TryParse fails to map it (case-insensitively) to a TraceCategory enum member. TraceCategory is a [Flags] enum; single-string form must be exactly one defined member name (e.g. "Command", "Mouse", "None", "All").

Source

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

    public override TraceCategory Read (ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        if (reader.TokenType == JsonTokenType.Number)
        {
            // Handle numeric format: 6
            return (TraceCategory)reader.GetInt32 ();
        }

        if (reader.TokenType == JsonTokenType.String)
        {
            // Handle single string: "Command"
            string value = reader.GetString ()!;

            if (Enum.TryParse (value, true, out TraceCategory result))
            {
                return result;
            }

            throw new JsonException ($"Invalid TraceCategory value: '{value}'");
        }

        if (reader.TokenType == JsonTokenType.StartArray)
        {
            // Handle array format: ["Command", "Mouse"]
            var result = TraceCategory.None;

            while (reader.Read ())
            {
                if (reader.TokenType == JsonTokenType.EndArray)
                {
                    break;
                }

                if (reader.TokenType != JsonTokenType.String)
                {
                    throw new JsonException ($"Unexpected token type in TraceCategory array: {reader.TokenType}");
                }

View on GitHub (pinned to 2e47b11478)

Solutions

Use a valid TraceCategory enum name (check the enum definition in Tracing/TraceCategory.cs for the current members).
If you want multiple categories, use the array form ["Command","Mouse"] instead of a comma-separated string.
Use the integer form (e.g. 6) if you know the combined flags value.

Example fix

// before
"TraceCategory": "Comand"
// after
"TraceCategory": "Command"
// or for multiple
"TraceCategory": ["Command", "Mouse"]

Defensive patterns

Strategy: validation

Validate before calling

// Validate a TraceCategory name before relying on JSON
bool IsValidTraceCategoryName (string s) => Enum.TryParse<TraceCategory> (s, true, out _);

Type guard

static bool IsValidTraceCategory (string value) => Enum.TryParse<TraceCategory> (value, true, out _);

Try / catch

ConfigurationManager.ThrowOnJsonErrors = false; // logs the bad value instead of throwing

Prevention

Use intellisense/the enum definition to pick valid TraceCategory names.
Use the array form for multiple categories, not a comma-separated string.
Lint config JSON in CI with a schema that enumerates allowed TraceCategory names.

When it happens

Trigger: A config file sets a TraceCategory-valued property (e.g. a tracing filter) to a string that isn't a TraceCategory member — typos like "Comand", made-up names like "Network", or values that only make sense as a combination but are written as a single string.

Common situations: Hand-editing config.json and misspelling a category; copying a category name from old docs that no longer exists after a rename; mixing the array and scalar forms incorrectly.

Related errors

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