SixLabors/ImageSharp · error · ArgumentOutOfRangeException

Unsupported color hex format.

Error message

Unsupported color hex format.

What it means

Color.ToHex validates the requested ColorHexFormat enum value; only Argb and Rgba are supported, and any other value (invalid cast, uninitialized enum, out-of-range int) hits the switch's discard arm and throws ArgumentOutOfRangeException with 'Unsupported color hex format.'

Solutions

1. Only pass ColorHexFormat.Rgba or ColorHexFormat.Argb
2. Validate untrusted enum values with Enum.IsDefined(typeof(ColorHexFormat), value) before calling ToHex
3. Fix deserialization that produced an undefined enum value

Example fix

// before
var hex = color.ToHex((ColorHexFormat)storedInt);
// after
var format = Enum.IsDefined(typeof(ColorHexFormat), storedInt) ? (ColorHexFormat)storedInt : ColorHexFormat.Rgba;
var hex = color.ToHex(format);

if (format is not (ColorHexFormat.Rgba or ColorHexFormat.Argb)) format = ColorHexFormat.Rgba;

bool IsKnownFormat(ColorHexFormat f) => Enum.IsDefined(f);

try { return color.ToHex(format); } catch (ArgumentOutOfRangeException) { return color.ToHex(ColorHexFormat.Rgba); }

When it happens

Trigger: Calling color.ToHex(format) with a ColorHexFormat value outside the defined members — typically from an unchecked (ColorHexFormat)cast of an int, a deserialized enum value, or default(ColorHexFormat) if the enum's zero value is not a valid member.

Common situations: Enum values round-tripped through config/JSON/DB as ints; API version changes adding/removing members; callers computing format values arithmetically.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• maxDegreeOfParallelism
• Hexadecimal string is not in the correct format.
• Input string is not in the correct format.
• Source PCS to target PCS is not supported
• Source PCS is not supported

AI-assisted analysis of SixLabors/ImageSharp@59ce6af6fc (2026-09-13). Data as JSON: /api/errors/bf2cca096f5302b0. Report an issue: GitHub.

Appendix: source

Thrown at src/ImageSharp/Color/Color.cs:375

    /// <summary>
    /// Gets the hexadecimal string representation of the color instance.
    /// </summary>
    /// <param name="format">
    /// The format of the hexadecimal string to return. Defaults to <see cref="ColorHexFormat.Rgba"/>.
    /// </param>
    /// <returns>A hexadecimal string representation of the value.</returns>
    /// <exception cref="ArgumentOutOfRangeException">Thrown when the <paramref name="format"/> is not supported.</exception>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    public string ToHex(ColorHexFormat format = ColorHexFormat.Rgba)
    {
        Rgba32 rgba = this.ToPixel<Rgba32>();

        uint hexOrder = format switch
        {
            ColorHexFormat.Argb => (uint)((rgba.B << 0) | (rgba.G << 8) | (rgba.R << 16) | (rgba.A << 24)),
            ColorHexFormat.Rgba => (uint)((rgba.A << 0) | (rgba.B << 8) | (rgba.G << 16) | (rgba.R << 24)),
            _ => throw new ArgumentOutOfRangeException(nameof(format), format, "Unsupported color hex format.")
        };

        return hexOrder.ToString("X8", CultureInfo.InvariantCulture);
    }

    /// <inheritdoc />
    public override string ToString() => this.ToHex(ColorHexFormat.Rgba);

    /// <summary>
    /// Converts the color instance to a specified <typeparamref name="TPixel"/> type.
    /// </summary>
    /// <typeparam name="TPixel">The pixel type to convert to.</typeparam>
    /// <returns>The <typeparamref name="TPixel"/>.</returns>
    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    public TPixel ToPixel<TPixel>()
        where TPixel : unmanaged, IPixel<TPixel>
    {
        if (this.boxedHighPrecisionPixel is TPixel pixel)

View on GitHub (pinned to 59ce6af6fc)