cefsharp/CefSharp · error · JsonException

Unable to convert Enum

Error message

Unable to convert Enum

What it means

Thrown by JsonEnumConverterFactory when deserializing an enum and no enum field's [JsonPropertyName] attribute matches the incoming JSON value. The converter iterates enum fields, reads each field's single JsonPropertyNameAttribute via .Single(), and if none equal the value it throws JsonException. Note .Single() itself throws InvalidOperationException if a field lacks or has multiple such attributes, and GetField(name) can be null.

Source

Thrown at CefSharp/Internals/Json/JsonEnumConverterFactory.cs:59

            return converter;
        }

        public static object ConvertStringToEnum(string val, Type typeToConvert)
        {
            foreach (var name in Enum.GetNames(typeToConvert))
            {
                var attribute = typeToConvert.GetField(name)
                    .GetCustomAttributes(false)
                    .OfType<JsonPropertyNameAttribute>()
                    .Single();

                if (attribute.Name == val)
                {
                    return Enum.Parse(typeToConvert, name);
                }
            }

            throw new JsonException("Unable to convert Enum");
        }

        public static string ConvertEnumToString(object value)
        {
            var type = value.GetType();
            var name = Enum.GetName(type, value);
            var attribute = type.GetField(name)
                .GetCustomAttributes(false)
                .OfType<JsonPropertyNameAttribute>()
                .Single();

            return attribute.Name;
        }
    }
}

View on GitHub (pinned to 16bc6e0711)

Solutions

1. Ensure every enum member has exactly one [JsonPropertyName] and the JSON sends that exact name.
2. Add the missing enum member / attribute for the value being sent.
3. Normalize JSON values (trim, exact casing) before deserialization.
4. If a fallback is acceptable, provide a JsonConverter that maps unknown values to a default instead of throwing.

Example fix

// before
public enum Status { [JsonPropertyName("ok")] Ok, Active } // 'Active' has no attribute; JSON "active" fails

// after
public enum Status { [JsonPropertyName("ok")] Ok, [JsonPropertyName("active")] Active }

static bool IsValidEnumValue<T>(string json) where T : struct, Enum
{
    var valid = typeof(T).GetFields()
        .Select(f => f.GetCustomAttributes(false).OfType<JsonPropertyNameAttribute>().SingleOrDefault()?.Name)
        .Where(n => n != null);
    return valid.Contains(json);
}

static bool IsValidEnumValue<T>(string json) where T : struct, Enum
{
    return typeof(T).GetFields()
        .Select(f => f.GetCustomAttributes(false).OfType<JsonPropertyNameAttribute>().SingleOrDefault()?.Name)
        .Contains(json);
}

try { result = JsonSerializer.Deserialize<T>(json, options); }
catch (JsonException ex) when (ex.Message.Contains("Unable to convert Enum"))
{ /* map unknown value to default or reject */ }

When it happens

Trigger: JSON contains an enum value that does not match any [JsonPropertyName] on the enum's fields; an enum field is missing the attribute; the enum was changed but the JSON sender uses old values; case or whitespace mismatch against the attribute Name.

Common situations: Version skew between the enum definition and the producer of the JSON; forgetting to decorate a new enum member with [JsonPropertyName]; sending the raw enum name instead of the JSON attribute name.

Related errors

• Not currently supported.
• {prop.Name} is required
• Current OS version is less than Windows 10. Applications not
• IBrowser
• Unable to add MessageId {0} to queuedCommandResults Concurre

AI-assisted analysis of cefsharp/CefSharp@16bc6e0711 (2026-08-13). Data as JSON: /api/errors/2bf32ec6c07606cd. Report an issue: GitHub.