What causes "'value' must be of type 'BitmapSource'." in dotnet/wpf?

Ensure value is a System.Windows.Media.Imaging.BitmapSource before calling (convert GDI images with Imaging.CreateBitmapSourceFromHBitmap, files with BitmapFrame.Create).

dotnet/wpf · error · ArgumentException

'value' must be of type 'BitmapSource'.

Error message

'value' must be of type 'BitmapSource'.

What it means

ImageSourceTypeConverter.ConvertTo casts the value parameter to BitmapSource; when the cast fails (value is not a BitmapSource and not null-castable) or the resulting reference is null, it throws ArgumentException with MustBeOfType("value", "BitmapSource"). The converter only serializes actual BitmapSource instances into the XPS package.

Solutions

Ensure value is a System.Windows.Media.Imaging.BitmapSource before calling (convert GDI images with Imaging.CreateBitmapSourceFromHBitmap, files with BitmapFrame.Create).
Null-check the image before serialization and substitute an empty/placeholder BitmapSource.
Catch ArgumentException around ConvertTo and report which image value was invalid.

Example fix

// before
converter.ConvertTo(context, culture, gdiBitmap, destinationType); // ArgumentException

// after
BitmapSource source = Imaging.CreateBitmapSourceFromHBitmap(
    gdiBitmap.GetHbitmap(), IntPtr.Zero, Int32Rect.Empty, BitmapSizeOptions.FromEmptyOptions());
converter.ConvertTo(context, culture, source, destinationType);

Defensive patterns

Strategy: type-guard

Validate before calling

if (value is not BitmapSource bitmapSource || bitmapSource == null)
{
    throw new ArgumentException($"Expected BitmapSource, got {value?.GetType().Name ?? "null"}");
}

Type guard

static bool IsBitmapSource(object value) => value is BitmapSource b && b != null;

// usage: if (!IsBitmapSource(value)) throw new ArgumentException(...);

Try / catch

try
{
    converter.ConvertTo(context, culture, value, destinationType);
}
catch (ArgumentException ex) when (ex.ParamName == null && ex.Message.Contains("BitmapSource"))
{
    // convert the offending value to a BitmapSource and retry
}

Prevention

Convert GDI+ Bitmaps via Imaging.CreateBitmapSourceFromHBitmap before serialization.
Null-check images that may have failed to load.
Keep a single conversion helper so every image entering serialization is a frozen BitmapSource.

When it happens

Trigger: Passing a non-BitmapSource object (e.g. an Image control, a string URI, a Bitmap directly, or null) as the value argument of ConvertTo while destinationType is supported.

Common situations: Serializing System.Drawing.Bitmap or GDI+ images without converting to BitmapSource first; passing null for an image that failed to load; passing UIElement wrappers instead of the underlying image source.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of dotnet/wpf@81131a70a4 (2026-09-14). Data as JSON: /api/errors/e91758ac5f04053a. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/ReachFramework/Serialization/ImageSourceTypeConverter.cs:162

            object                              value,
            Type                                destinationType
            )
        {
            Toolbox.EmitEvent(EventTrace.Event.WClientDRXConvertImageBegin);

            ArgumentNullException.ThrowIfNull(context);
            if (!IsSupportedType(destinationType))
            {
                throw new NotSupportedException(SR.Converter_ConvertToNotSupported);
            }

            //
            // Check that we have a valid BitmapSource instance.
            //
            BitmapSource bitmapSource = (BitmapSource)value;
            if (bitmapSource == null)
            {
                throw new ArgumentException(SR.Format(SR.MustBeOfType, "value", "BitmapSource"));
            }

            //
            // Get the current serialization manager.
            //
            PackageSerializationManager manager = (PackageSerializationManager)context.GetService(typeof(XpsSerializationManager));

            //Get the image Uri if it has already been serialized
            Uri imageUri = GetBitmapSourceFromImageTable(manager, bitmapSource);

            //
            // Get the current page image cache
            //
            Dictionary<int, Uri> currentPageImageTable = manager.ResourcePolicy.CurrentPageImageTable;
            if (imageUri != null)
            {
                int uriHashCode = imageUri.GetHashCode();
                if(!currentPageImageTable.ContainsKey(uriHashCode))

View on GitHub (pinned to 81131a70a4)