What causes "Image_MetadataNotCompatible" in dotnet/wpf?

Create BitmapMetadata with the container format matching the target encoder (e.g. new BitmapMetadata("/app1/ifd") for JPEG vs PNG GUID-based metadata)

dotnet/wpf · error · InvalidOperationException

Image_MetadataNotCompatible

Error message

Image_MetadataNotCompatible

What it means

The BitmapEncoder.Metadata setter requires that the metadata's GuidFormat matches the encoder's ContainerFormat; otherwise the metadata would be written into a container that cannot hold it, and InvalidOperationException(Image_MetadataNotCompatible) is thrown before the global-metadata capability check.

Solutions

Create BitmapMetadata with the container format matching the target encoder (e.g. new BitmapMetadata("/app1/ifd") for JPEG vs PNG GUID-based metadata)
Rebuild metadata for the target format instead of reusing the source metadata object
Compare metadata.GuidFormat to encoder.ContainerFormat before assigning
Clone/translate needed metadata fields manually when converting formats

Example fix

// before
pngEncoder.Metadata = jpegMetadata; // GuidFormat mismatch
// after
var pngMeta = new BitmapMetadata(MILGuidData.GUID_ContainerFormatPng.ToString());
pngMeta.SetQuery("/text", ...);
pngEncoder.Metadata = pngMeta;

Defensive patterns

Strategy: validation

Validate before calling

if (metadata.GuidFormat != encoder.ContainerFormat)
    throw new InvalidOperationException("Metadata GuidFormat does not match encoder container format");
encoder.Metadata = metadata;

Type guard

static bool IsCompatibleMetadata(BitmapEncoder e, BitmapMetadata m) => m.GuidFormat == e.ContainerFormat;

Try / catch

try { encoder.Metadata = metadata; }
catch (InvalidOperationException) when (metadata.GuidFormat != encoder.ContainerFormat) {
    encoder.Metadata = RebuildMetadataForFormat(metadata, encoder.ContainerFormat); }

Prevention

Never reuse a BitmapMetadata object across different container formats
Build metadata with the target format GUID at conversion time
Compare GuidFormat vs ContainerFormat before assignment
Translate needed fields explicitly when converting formats

When it happens

Trigger: Assigning encoder.Metadata = metadata whose GuidFormat differs from the encoder's container format (e.g. attaching a BitmapMetadata built for JPEG to a PngBitmapEncoder).

Common situations: Copying metadata across format conversions (re-encoding JPEG to PNG while reusing the original metadata object); constructing BitmapMetadata with the wrong container GUID.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationCore/System/Windows/Media/Imaging/BitmapEncoder.cs:190

        {
            get
            {
                VerifyAccess();
                EnsureBuiltIn();
                EnsureMetadata(true);

                return _metadata;
            }
            set
            {
                VerifyAccess();
                EnsureBuiltIn();

                ArgumentNullException.ThrowIfNull(value);

                if (value.GuidFormat != ContainerFormat)
                {
                    throw new InvalidOperationException(SR.Image_MetadataNotCompatible);
                }

                if (!_supportsGlobalMetadata)
                {
                    throw new InvalidOperationException(SR.Image_EncoderNoGlobalMetadata);
                }

                _metadata = value;
            }
        }

        /// <summary>
        /// Set or get the bitmap's global preview
        /// </summary>
        public virtual BitmapSource Preview
        {
            get
            {

View on GitHub (pinned to 81131a70a4)