AvaloniaUI/Avalonia · error · NotSupportedException

CopyPixels is not supported for this bitmap type

Error message

CopyPixels is not supported for this bitmap type

What it means

Thrown by the IntPtr-buffer CopyPixels overload when the bitmap cannot supply readable pixels in its declared format. The guard rejects three cases: Format is null (format-less/empty bitmap), the platform impl is not IReadableBitmapImpl (e.g. a GPU/deferred texture that cannot be locked for CPU reads), or the bitmap's Format differs from the readable impl's native Format. For transcoded or non-readable bitmaps you must go through the transcoding-aware CopyPixels(ILockedFramebuffer) overload instead.

Source

Thrown at src/Avalonia.Base/Media/Imaging/Bitmap.cs:285

        /// given framebuffer. Self-contained convenience wrapper around the static
        /// <see cref="CopyPixelsCore(PixelRect,IntPtr,int,PixelFormat,IntPtr,int,int)"/> for inheritors.
        /// </summary>
        private protected void CopyPixelsCore(PixelRect sourceRect, IntPtr buffer, int bufferSize, int stride,
            ILockedFramebuffer fb)
        {
            sourceRect = ValidateSourceRect(sourceRect);
            CopyPixelsCore(sourceRect, fb.Address, fb.RowBytes, fb.Format, buffer, bufferSize, stride);
        }

        public virtual void CopyPixels(PixelRect sourceRect, IntPtr buffer, int bufferSize, int stride)
        {
            if (
                Format == null
                || PlatformImpl.Item is not IReadableBitmapImpl readable
                || Format != readable.Format
            )
            {
                throw new NotSupportedException("CopyPixels is not supported for this bitmap type");
            }

            if (_isTranscoded)
                throw new NotSupportedException("CopyPixels is not supported for transcoded bitmaps");

            using (var fb = readable.Lock())
                CopyPixelsCore(sourceRect, buffer, bufferSize, stride, fb);
        }

        /// <summary>
        /// Copies pixels to the target buffer and transcodes the pixel and alpha format if needed.
        /// </summary>
        /// <param name="buffer">The target buffer.</param>
        /// <exception cref="NotSupportedException"></exception>
        public void CopyPixels(ILockedFramebuffer buffer)
        {
            if (PlatformImpl.Item is not IReadableBitmapImpl readable || readable.Format == null || readable.AlphaFormat == null)
            {

View on GitHub (pinned to 11c5427268)

Solutions

  1. Use the transcoding overload CopyPixels(ILockedFramebuffer buffer) (or the writeable path) which handles format conversion and does not require the raw-Format match.
  2. Confirm the bitmap was loaded/created from a source that yields an IReadableBitmapImpl before attempting raw pixel reads.
  3. If you control creation, build the bitmap with a platform-supported format and through Load() / WriteableBitmap so the impl is readable.
  4. Guard before calling: check Format != null and bitmap.PlatformImpl.Item is IReadableBitmapImpl.

Example fix

// before
bitmap.CopyPixels(rect, buffer, bufferSize, stride);

// after - use the transcoding framebuffer overload
var size = rect.Size;
using var fb = new WriteableBitmap(PixelFormat.Rgba8888, AlphaFormat.Premultiplied, size, 96.0, 96.0);
using (var l = fb.Lock())
    bitmap.CopyPixels(l);
Defensive patterns

Strategy: validation

Validate before calling

// Validate the bitmap is readable in its own format before the raw CopyPixels call.
bool CanCopyRaw(Bitmap b) =>
    b.Format is not null
    && b.PlatformImpl?.Item is IReadableBitmapImpl readable
    && b.Format == readable.Format;

if (!CanCopyRaw(bitmap))
    throw new InvalidOperationException("Bitmap is not raw-readable; use the framebuffer overload.");

Type guard

static bool IsRawReadable(Bitmap b) =>
    b.Format is not null && b.PlatformImpl?.Item is IReadableBitmapImpl r && b.Format == r.Format;

Prevention

When it happens

Trigger: Calling bitmap.CopyPixels(sourceRect, buffer, bufferSize, stride) on a bitmap whose PlatformImpl.Item does not implement IReadableBitmapImpl, or whose Format is null, or whose Format mismatches readable.Format. Typical with platform-specific loaded bitmaps (e.g. D2D/Skia decoded textures) or an empty/placeholder Bitmap.

Common situations: Loading an image with a render backend that does not expose a readable framebuffer; using a bitmap produced by a GPU render target; calling CopyPixels on a Bitmap constructed but never given pixel data; cross-backend bitmaps where Format was set to a value the impl does not match.

Related errors

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