tui-cs/Terminal.Gui · error · JsonException

Unexpected token when parsing Rune: {reader.TokenType}.

Error message

Unexpected token when parsing Rune: {reader.TokenType}.

What it means

The Rune converter received a JSON token that is neither String, Number, nor Null — e.g. True, False, StartArray, or StartObject. Rune only deserializes from those three token kinds; anything else hits the default switch arm.

Source

Thrown at Terminal.Gui/Configuration/RuneJsonConverter.cs:135

                    }

                    return new (combined [0]);
                }
            case JsonTokenType.Number:
                {
                    uint num = reader.GetUInt32 ();

                    if (Rune.IsValid (num))
                    {
                        return new (num);
                    }

                    throw new JsonException ($"{num}: Invalid Rune (not a scalar Unicode value).");
                }
            case JsonTokenType.Null:
                return default;
            default:
                throw new JsonException ($"Unexpected token when parsing Rune: {reader.TokenType}.");
        }
    }

    public override void Write (Utf8JsonWriter writer, Rune value, JsonSerializerOptions options)
    {
        Rune printable = value.MakePrintable ();
        if (printable == Rune.ReplacementChar)
        {
            // Write as /u string
            writer.WriteRawValue ($"\"{value}\"");
        }
        else
        {
            // Write as the actual glyph
            writer.WriteStringValue (value.ToString ());
        }
    }
}

View on GitHub (pinned to 2e47b11478)

Solutions

1. Provide the Rune as a string ("a", "U+0061", "\u0061") or a decimal number (97).
2. Fix the upstream generator so it emits strings or numbers for Rune fields.

Example fix

// before
"CheckMark": true
// after
"CheckMark": "U+2611"

using var doc = JsonDocument.Parse (configText);
// walk to each Rune-typed property and assert its ValueKind is String or Number
bool ok = prop.Value.ValueKind is JsonValueKind.String or JsonValueKind.Number;

try { ConfigurationManager.Apply (); }
catch (JsonException ex) when (ex.Message.Contains ("Unexpected token when parsing Rune"))
{ /* report the token type from ex.Message */ }

When it happens

Trigger: Config JSON has a boolean, array, or object where a Rune is expected, e.g. "CheckMark": true or "CheckMark": [97].

Common situations: YAML→JSON conversion artifacts; misunderstanding the Rune config format; a generator emitting wrong types.

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

• {value}: Invalid Rune. The second codepoint is not valid: {s
• {value}: Invalid Rune. The second codepoint is not a combini
• {value}: Invalid combined Rune.
• {num}: Invalid Rune (not a scalar Unicode value).
• {propertyType.Name}: Error reading property with converter "

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