dotnet/wpf · error · ArgumentException

SR.Image_AlphaThresholdOutOfRange

Error message

SR.Image_AlphaThresholdOutOfRange

What it means

FormatConvertedBitmap's constructor validates that alphaThreshold is a percentage within [0, 100]. Values outside this range cannot be used for alpha-threshold conversion, so an ArgumentException is thrown before initialization begins.

Solutions

  1. Clamp the value: Math.Max(0, Math.Min(100, alphaThreshold))
  2. Convert from 0-255 scale: alphaThreshold = alpha255 * 100.0 / 255.0
  3. Pass 0 (no thresholding) or 100 (full thresholding) if unsure

Example fix

// before
byte alpha = 128;
var fcb = new FormatConvertedBitmap(src, PixelFormats.Bgr32, null, alpha); // 128 > 100, throws
// after
byte alpha = 128;
double alphaThreshold = alpha * 100.0 / 255.0; // ~50.2
var fcb = new FormatConvertedBitmap(src, PixelFormats.Bgr32, null, alphaThreshold);
Defensive patterns

Strategy: validation

Validate before calling

static double NormalizeAlphaThreshold(double t) => double.IsNaN(t) ? 0 : Math.Clamp(t, 0.0, 100.0);

Type guard

static bool IsValidAlphaThreshold(double t) => t >= 0.0 && t <= 100.0 && !double.IsNaN(t);

Try / catch

try { return new FormatConvertedBitmap(src, fmt, palette, alphaThreshold); }
catch (ArgumentException ex) when (ex.Message.Contains("AlphaThreshold")) { return new FormatConvertedBitmap(src, fmt, palette, Math.Clamp(alphaThreshold, 0, 100)); }

Prevention

When it happens

Trigger: new FormatConvertedBitmap(source, format, palette, -1) or alphaThreshold = 150, NaN passed through comparisons; any double outside 0..100 including negative opacity-derived values.

Common situations: Passing an alpha in 0..255 (byte) units instead of 0..100 percent; sign errors; computing the threshold from a config value with wrong scale.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

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

        /// </summary>
        public FormatConvertedBitmap() : base(true)
        {
        }

        /// <summary>
        /// Construct a FormatConvertedBitmap
        /// </summary>
        /// <param name="source">BitmapSource to apply to the format conversion to</param>
        /// <param name="destinationFormat">Destionation Format to  apply to the bitmap</param>
        /// <param name="destinationPalette">Palette if format is palettized</param>
        /// <param name="alphaThreshold">Alpha threshold</param>
        public FormatConvertedBitmap(BitmapSource source, PixelFormat destinationFormat, BitmapPalette destinationPalette, double alphaThreshold)
            : base(true) // Use base class virtuals
        {
            ArgumentNullException.ThrowIfNull(source);
            if (alphaThreshold < (double)(0.0) || alphaThreshold > (double)(100.0))
            {
                throw new ArgumentException(SR.Image_AlphaThresholdOutOfRange);
            }

            _bitmapInit.BeginInit();

            Source = source;
            DestinationFormat = destinationFormat;
            DestinationPalette = destinationPalette;
            AlphaThreshold = alphaThreshold;

            _bitmapInit.EndInit();
            FinalizeCreation();
        }

        // ISupportInitialize

        /// <summary>
        /// Prepare the bitmap to accept initialize paramters.
        /// </summary>

View on GitHub (pinned to 81131a70a4)