What causes "Pixel format {format} is not supported" in AvaloniaUI/Avalonia?

Use a PixelFormat covered by the reader (e.g. Rgba8888, Bgra8888, Rgb24, Bgr24).

AvaloniaUI/Avalonia · error · NotSupportedException

Pixel format {format} is not supported

Error message

Pixel format {format} is not supported

What it means

PixelFormatReader.Read supports a fixed set of formats (Rgb565, Rgba8888, Bgra8888, BlackWhite, Gray2, Gray4, Gray8, Gray16, Gray32Float, Rgba64, Rgb24, Rgb32, Bgr24, Bgr32, Bgr555, Bgr565). Any other PixelFormatEnum value hits the default and throws NotSupportedException. This is the software fallback read path used to convert source pixels into an Rgba8888Pixel span for transcoding.

Source

Thrown at src/Avalonia.Base/Media/Imaging/PixelFormatReaders.cs:494

                Read<Rgb24PixelFormatReader>(pixels, source, size, stride);
                break;
            case PixelFormatEnum.Rgb32:
                Read<Rgb32PixelFormatReader>(pixels, source, size, stride);
                break;
            case PixelFormatEnum.Bgr24:
                Read<Bgr24PixelFormatReader>(pixels, source, size, stride);
                break;
            case PixelFormatEnum.Bgr32:
                Read<Bgr32PixelFormatReader>(pixels, source, size, stride);
                break;
            case PixelFormatEnum.Bgr555:
                Read<Bgr555PixelFormatReader>(pixels, source, size, stride);
                break;
            case PixelFormatEnum.Bgr565:
                Read<Bgr565PixelFormatReader>(pixels, source, size, stride);
                break;
            default:
                throw new NotSupportedException($"Pixel format {format} is not supported");
        }
    }
}

View on GitHub (pinned to 11c5427268)

Solutions

Use a PixelFormat covered by the reader (e.g. Rgba8888, Bgra8888, Rgb24, Bgr24).
Prefer a format natively supported by IPlatformRenderInterface so software transcoding is never invoked.
If you added a custom format, also add a matching reader/writer case.

Example fix

// before
new WriteableBitmap(customFormat, AlphaFormat.Premultiplied, size, dpi);
// -> CreatePlatformImpl software fallback -> reader throws

// after
new WriteableBitmap(PixelFormat.Bgra8888, AlphaFormat.Premultiplied, size, dpi);

Defensive patterns

Strategy: validation

Validate before calling

if (!PixelFormatReader.SupportsFormat(format))
    throw new NotSupportedException($"Format {format} has no software reader.");
PixelFormatReader.Read(pixels, source, size, stride, format);

Type guard

static bool IsReadableFormat(PixelFormat f) => PixelFormatReader.SupportsFormat(f);

Prevention

Stick to standard formats present in the reader's switch.
When adding a PixelFormat, add a matching reader case.
Prefer formats natively supported by the render backend to skip software transcoding.

When it happens

Trigger: Passing a PixelFormat whose FormatEnum is not one of the listed cases into the software pixel reader — typically triggered indirectly when the platform backend does not support a format and Avalonia falls back to software transcoding, but the format is also absent from the software reader.

Common situations: Introducing a custom PixelFormat via the extensible PixelFormat model; loading/creating a bitmap in a format newer than the reader covers; version skew where a format exists in the enum but no reader case was added.

Related errors

AI-assisted analysis of AvaloniaUI/Avalonia@11c5427268 (2026-08-13). Data as JSON: /api/errors/19de42f92ef06294. Report an issue: GitHub.