reactiveui/refit · error · JsonException

Unsupported enum backing type for {typeof(TEnum)}.

Error message

Unsupported enum backing type for {typeof(TEnum)}.

What it means

Thrown by EnumHelpers.ReadJsonNumericValue when the enum's underlying TypeCode is not one of the supported integral types (sbyte, byte, short, ushort, int, uint, long, ulong). It is a defensive exhaustiveness check in the switch; in practice every valid .NET enum is backed by one of these, so reaching it implies a malformed or non-enum generic instantiation.

Source

Thrown at src/Refit/EnumHelpers.cs:122

            ReadJsonNumericValue(_underlyingTypeCode, ref reader);

        /// <summary>Reads an undefined enum value using the supplied backing type code.</summary>
        /// <param name="underlyingTypeCode">The enum backing type code.</param>
        /// <param name="reader">The JSON reader positioned at a numeric token.</param>
        /// <returns>The enum value represented by the numeric token.</returns>
        /// <exception cref="JsonException"><paramref name="underlyingTypeCode"/> is not one of the integral type codes an enum can be backed by.</exception>
        internal static TEnum ReadJsonNumericValue(TypeCode underlyingTypeCode, ref Utf8JsonReader reader) =>
            underlyingTypeCode switch
            {
                TypeCode.SByte => ToEnum(checked((sbyte)reader.GetInt64())),
                TypeCode.Byte => ToEnum(checked((byte)reader.GetUInt64())),
                TypeCode.Int16 => ToEnum(checked((short)reader.GetInt64())),
                TypeCode.UInt16 => ToEnum(checked((ushort)reader.GetUInt64())),
                TypeCode.Int32 => ToEnum(checked((int)reader.GetInt64())),
                TypeCode.UInt32 => ToEnum(checked((uint)reader.GetUInt64())),
                TypeCode.Int64 => ToEnum(reader.GetInt64()),
                TypeCode.UInt64 => ToEnum(reader.GetUInt64()),
                _ => throw new JsonException($"Unsupported enum backing type for {typeof(TEnum)}.")
            };

        /// <summary>Writes an undefined enum value using the correct signedness for the enum backing type.</summary>
        /// <param name="writer">The JSON writer.</param>
        /// <param name="value">The enum value to write.</param>
        internal static void WriteJsonNumericValue(Utf8JsonWriter writer, TEnum value)
        {
            if (IsUnsignedBackingType(_underlyingTypeCode))
            {
                writer.WriteNumberValue(ToUInt64(value));
                return;
            }

            writer.WriteNumberValue(ToInt64(value));
        }

        /// <summary>Converts an enum value to a signed 64-bit number without boxing.</summary>
        /// <param name="value">The enum value.</param>

View on GitHub (pinned to b455f65ecc)

Solutions

1. Ensure TEnum is a proper enum type (where TEnum : struct, Enum) and not a class/struct masquerading as one.
2. If you wrote a custom converter around EnumHelpers, validate TEnum.IsEnum and that its underlying type is a supported integral type before use.
3. Report it as a Refit bug if it occurs with a legitimate enum, since all standard enums should be covered.

// Verify TEnum is a real enum with a supported backing type before use.
static bool IsValidEnumType<TEnum>() where TEnum : struct
{
    var t = typeof(TEnum);
    if (!t.IsEnum) return false;
    var code = Type.GetTypeCode(Enum.GetUnderlyingType(t));
    return code is TypeCode.SByte or TypeCode.Byte or TypeCode.Int16 or TypeCode.UInt16
        or TypeCode.Int32 or TypeCode.UInt32 or TypeCode.Int64 or TypeCode.UInt64;
}

When it happens

Trigger: The generic TEnum passed to EnumHelpers.Info<TEnum> is not a real enum (e.g. it was forced via reflection/Unsafe) or its Enum.GetUnderlyingType returned an unexpected TypeCode. ReadJsonNumericValue is hit when a JSON number is being mapped to the enum.

Common situations: Extremely rare for end users — essentially only if TEnum is mis-bound (abuse of generics, a build/trimming issue, or a custom converter using EnumHelpers on a non-enum type). It signals an internal contract violation more than a usage mistake.

Related errors

• Enum {typeof(TEnum)} does not use a signed backing type.
• Enum {typeof(TEnum)} does not use an unsigned backing type.
• Cannot convert an empty value to {typeof(TEnum)}.
• Unable to convert '{value}' to {typeof(TEnum)}.
• Unexpected token {reader.TokenType} when parsing {typeof(TEn

AI-assisted analysis of reactiveui/refit@b455f65ecc (2026-08-13). Data as JSON: /api/errors/5b8d0323aa6d754e. Report an issue: GitHub.