ElectronNET/Electron.NET · error · JsonException

Invalid value for TitleBarOverlay. Expected boolean or an…

Error message

Invalid value for TitleBarOverlay. Expected boolean or an object.

What it means

TitleBarOverlayConverter.Read only accepts a JSON boolean or object for TitleBarOverlay values; anything else (string, number, array, null token variants it does not handle) triggers this JsonException. The converter exists because the Windows titleBarOverlay option can be either a boolean flag or an options object.

Solutions

1. Send titleBarOverlay as a real boolean (true/false) or a plain object, not a string
2. Remove quotes around the value in the calling code or JSON payload
3. If using custom JS, ensure JSON.parse is applied before sending to the bridge

Example fix

// before
win.setTitleBarOverlay("true");
// after
win.setTitleBarOverlay(true);
// or
win.setTitleBarOverlay({ color: '#000000', symbolColor: '#ffffff' });

// client-side: ensure titleBarOverlay is bool or object before sending
const ok = typeof titleBarOverlay === 'boolean' ||
           (titleBarOverlay !== null && typeof titleBarOverlay === 'object' && !Array.isArray(titleBarOverlay));
if (!ok) throw new TypeError('titleBarOverlay must be a boolean or object');

static bool IsValidTitleBarOverlay(JsonElement e) =>
    e.ValueKind is JsonValueKind.True or JsonValueKind.False or JsonValueKind.Object;

try
{
    var overlay = doc.RootElement.Deserialize<TitleBarOverlay>(ElectronJson.Options);
}
catch (JsonException ex)
{
    logger.LogWarning(ex, "Invalid titleBarOverlay value in payload");
}

When it happens

Trigger: Calling Electron.WindowManager or BrowserWindow APIs (e.g. setTitleBarOverlay, window options) with a titleBarOverlay value serialized as a string like "true" or "overlay", or any non-boolean/non-object JSON token.

Common situations: Passing titleBarOverlay options from client-side JS as a JSON string instead of a real object/boolean; older bridge clients sending wrong types; hand-written config JSON quoting the value.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Unexpected token when reading releaseNotes.
• Expected array for ModifierType list
• Expected string enum value
• Invalid value for PageSize. Expected string or an object.
• Unsupported token

AI-assisted analysis of ElectronNET/Electron.NET@87cc6f98b6 (2026-09-14). Data as JSON: /api/errors/b808b12b83971f17. Report an issue: GitHub.

Appendix: source

Thrown at src/ElectronNET.API/Converter/TitleBarOverlayConverter.cs:24

namespace ElectronNET.Converter;

public class TitleBarOverlayConverter : JsonConverter<TitleBarOverlay>
{
    public override TitleBarOverlay Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        if (reader.TokenType == JsonTokenType.True || reader.TokenType == JsonTokenType.False)
        {
            return (bool)reader.GetBoolean();
        }
        else if (reader.TokenType == JsonTokenType.StartObject)
        {
            using var doc = JsonDocument.ParseValue(ref reader);
            return doc.RootElement.Deserialize<TitleBarOverlay>(ElectronJson.Options);
        }
        else
        {
            throw new JsonException("Invalid value for TitleBarOverlay. Expected boolean or an object.");
        }
    }

    public override void Write(Utf8JsonWriter writer, TitleBarOverlay value, JsonSerializerOptions options)
    {
        if (value is null)
        {
            return;
        }

        var @bool = (bool?)value;
        if (@bool.HasValue)
        {
            writer.WriteBooleanValue(@bool.Value);
        }
        else
        {
            JsonSerializer.Serialize(writer, value, ElectronJson.Options);

View on GitHub (pinned to 87cc6f98b6)