tui-cs/Terminal.Gui · error · JsonException

{num}: Invalid Rune (not a scalar Unicode value).

Error message

{num}: Invalid Rune (not a scalar Unicode value).

What it means

A JSON number token is used where a Rune is expected, but the number is not a valid Unicode scalar value (in the surrogate range U+D800–U+DFFF, or greater than U+10FFFF). The converter accepts decimal numbers as codepoints (97 = 'a'), but invalid ranges are rejected by Rune.IsValid.

Source

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

                    string combined = string.Concat ((char)first, (char)second).Normalize ();

                    if (!Rune.IsValid (combined [0]))
                    {
                        throw new JsonException ($"{value}: Invalid combined Rune.");
                    }

                    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
        {

View on GitHub (pinned to 2e47b11478)

Solutions

1. Use a valid scalar codepoint number (0–55295 or 57344–1114111).
2. Switch to the "U+XXXX" string form to avoid decimal conversion errors.
3. Prefer the glyph or \u string form for readability.

Example fix

// before
"Glyph": 55296
// after
"Glyph": 97   // or "U+0061"

static bool IsValidNumericRune (uint n) => System.Text.Rune.IsValid (n);

try { ConfigurationManager.Apply (); }
catch (JsonException ex) when (ex.Message.Contains ("not a scalar Unicode value"))
{ /* report offending number from ex.Message */ }

When it happens

Trigger: Config has a numeric Rune value such as 55296 (0xD800), 1114112 (0x110000), or any number in the surrogate range.

Common situations: Authoring config with numeric codepoints and mistyping; copying a decimal from a surrogate listing; an off-by-one in hex→decimal conversion.

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.
• {value}: Invalid Rune.
• {value}: Invalid Rune

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