dotnet/wpf · error · InvalidOperationException

SR.Image_PaletteColorsDoNotMatchFormat

Error message

SR.Image_PaletteColorsDoNotMatchFormat

What it means

For indexed pixel formats, the palette cannot contain more colors than the bit depth can index ((1 << BitsPerPixel) must be >= Colors.Count). FormatConvertedBitmap throws this InvalidOperationException during EndInit when DestinationPalette holds more color entries than the DestinationFormat can address.

Solutions

  1. Trim the palette to at most (1 << DestinationFormat.BitsPerPixel) colors before assigning it.
  2. Choose a DestinationFormat with enough bits per pixel for the palette size (e.g. Indexed8Colors for a 256-color palette).
  3. Quantize the source image first (e.g. via an encoder or external quantizer) to produce a palette matching the target depth.

Example fix

// before
fcb.DestinationFormat = PixelFormats.Indexed4Colors; // 16 colors max
fcb.DestinationPalette = BitmapPalettes.WebPalette; // 216+ colors -> throws

// after
fcb.DestinationFormat = PixelFormats.Indexed8Colors; // 256 colors max
fcb.DestinationPalette = BitmapPalettes.WebPalette;
Defensive patterns

Strategy: validation

Validate before calling

if (palette != null && palette.Colors.Count > (1 << format.BitsPerPixel))
    throw new ArgumentException($"Palette has {palette.Colors.Count} colors; {format.BitsPerPixel}bpp supports at most {1 << format.BitsPerPixel}.");

Type guard

static bool PaletteFits(PixelFormat f, BitmapPalette p) => p == null || p.Colors.Count <= (1 << f.BitsPerPixel);

Try / catch

try { fcb.EndInit(); } catch (InvalidOperationException ex) { /* shrink palette or raise bpp, then retry */ }

Prevention

When it happens

Trigger: EndInit on a FormatConvertedBitmap where e.g. DestinationFormat = Indexed1Colors (2 possible colors, 1bpp) but DestinationPalette contains 3+ entries; generally any palette whose Colors.Count exceeds 2^BitsPerPixel.

Common situations: Reusing a 256-color WebPalette with Indexed4Colors or Indexed1Formats; building a custom BitmapPalette from a source image's many colors and applying it to a low-bit-depth target; copy-pasted palette code without matching the bit depth.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationCore/System/Windows/Media/Imaging/FormatConvertedBitmap.cs:187

                    throw new InvalidOperationException(SR.Format(SR.Image_NoArgument, "Source"));
                }
                return false;
            }
            if (DestinationFormat.Palettized)
            {
                if (DestinationPalette == null)
                {
                    if (throwIfInvalid)
                    {
                        throw new InvalidOperationException(SR.Image_IndexedPixelFormatRequiresPalette);
                    }
                    return false;
                }
                else if ((1 << DestinationFormat.BitsPerPixel) < DestinationPalette.Colors.Count)
                {
                    if (throwIfInvalid)
                    {
                        throw new InvalidOperationException(SR.Image_PaletteColorsDoNotMatchFormat);
                    }
                    return false;
                }
            }

            return true;
        }

        /// <summary>
        ///     Notification on destination format changing.
        /// </summary>
        private void DestinationFormatPropertyChangedHook(DependencyPropertyChangedEventArgs e)
        {
            if (!e.IsASubPropertyChange)
            {
                _destinationFormat = (PixelFormat)e.NewValue;
            }
        }

View on GitHub (pinned to 81131a70a4)