tui-cs/Terminal.Gui · error · JsonException

Unexpected StartObject token when parsing Attribute: {reader

Error message

Unexpected StartObject token when parsing Attribute: {reader.TokenType}.

What it means

Thrown as JsonException by AttributeJsonConverter.Read when the reader is not positioned on a StartObject token. An Attribute in Terminal.Gui config JSON must be a JSON object like {"Foreground":..., "Background":...}. Supplying a bare string, number, array, or a pre-consumed token produces this error with the offending TokenType in the message.

Source

Thrown at Terminal.Gui/Configuration/AttributeJsonConverter.cs:29

    /// <summary></summary>
    public static AttributeJsonConverter Instance
    {
        get
        {
            if (_instance is null)
            {
                _instance = new AttributeJsonConverter ();
            }

            return _instance;
        }
    }

    public override Attribute Read (ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        if (reader.TokenType != JsonTokenType.StartObject)
        {
            throw new JsonException ($"Unexpected StartObject token when parsing Attribute: {reader.TokenType}.");
        }

        var attribute = new Attribute ();
        Color? foreground = null;
        Color? background = null;
        TextStyle? style = null;

        string propertyName = string.Empty;

        while (reader.Read ())
        {
            if (reader.TokenType == JsonTokenType.EndObject)
            {
                if (foreground is null || background is null)
                {
                    throw new JsonException ($"{propertyName}: Both Foreground and Background colors must be provided.");
                }

View on GitHub (pinned to 2e47b11478)

Solutions

1. Ensure every Attribute value in config JSON is an object with at least Foreground and Background keys.
2. Validate the config JSON against the expected schema before applying it with ConfigurationManager.
3. Use the format { "Foreground": { ... }, "Background": { ... } } and optionally "Style": "Bold".

Example fix

// before (config.json)
"Normal": "red"

// after
"Normal": { "Foreground": "red", "Background": "black" }

// Validate config JSON before applying:
// every Attribute must be a JSON object, not a scalar or array.
var doc = JsonDocument.Parse (configText);
foreach (var attr in /* locate Attribute nodes */)
{
    if (attr.ValueKind != JsonValueKind.Object)
    {
        throw new InvalidOperationException ($"Attribute must be an object, got {attr.ValueKind}");
    }
}

try
{
    ConfigurationManager.Load (configText);
}
catch (JsonException ex)
{
    Logging.Error ($"Bad config JSON for Attribute: {ex.Message}");
}

When it happens

Trigger: Writing a Scheme/Attribute in a theme JSON config file as a shorthand string (e.g. "red") instead of an object; nesting Attribute where a different type was expected; a malformed config file from a manual edit or a bad config generator.

Common situations: Hand-editing a Terminal.Gui theme/config JSON and using the wrong shape for an attribute; migrating an old config format that used string color names; tooling that emits the wrong JSON node type for color attributes.

Related errors

• {propertyName}: Both Foreground and Background colors must b
• {propertyName}: Json error in ScopeJsonConverter
• {p.Key}: Unsupported configuration converter type "{converte
• {p.Key}: No source-generated JsonTypeInfo is registered for
• {propertyType.FullName}: No source-generated JsonTypeInfo is

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