dotnet/wpf · error · ArgumentException

SR.InvalidHighlightColor

Error message

SR.InvalidHighlightColor

What it means

CreateHighlightForSelection requires the highlightBrush to be a SolidColorBrush because the highlight color is stored as a byte alpha + color. Passing any other Brush type (LinearGradientBrush, ImageBrush, etc.) throws ArgumentException.

Solutions

  1. Pass a SolidColorBrush, e.g. Brushes.Yellow or new SolidColorBrush(Color.FromArgb(255,255,255,0)).
  2. Freeze the SolidColorBrush for performance: brush.Freeze().
  3. If you have a generic Brush, extract its color or fall back to a default SolidColorBrush.
  4. Catch ArgumentException and report that only solid brushes are supported.

Example fix

// before
var brush = (Brush)FindResource("BrandGradient");
AnnotationHelper.CreateHighlightForSelection(service, brush);
// after
var brush = new SolidColorBrush(Colors.Yellow);
brush.Freeze();
AnnotationHelper.CreateHighlightForSelection(service, brush);
Defensive patterns

Strategy: type-guard

Validate before calling

bool IsSolidBrush(Brush b) => b is SolidColorBrush;

Type guard

bool IsSolidBrush(Brush? b) => b is SolidColorBrush;

Try / catch

try { AnnotationHelper.CreateHighlightForSelection(service, brush); } catch (ArgumentException ex) { log.Error("Highlight brush must be a SolidColorBrush: " + ex.Message); }

Prevention

When it happens

Trigger: Calling AnnotationHelper.CreateHighlightForSelection with a brush that is not a SolidColorBrush, e.g. a gradient or resource-based brush from theme dictionaries.

Common situations: Passing Brushes-derived resources that resolve to gradients, binding the brush parameter to a user-configured brush, or passing SystemColors brushes that are solid (fine) versus custom gradient definitions (not).

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/4c60b50b6fccb18a. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/Annotations/AnnotationHelper.cs:928

        {
            CheckInputs(service);

            // Get the selection for the viewer and wrap it in a TextRange
            ITextSelection selection = GetTextSelection((FrameworkElement)service.Root);
            Invariant.Assert(selection != null, "TextSelection is null");

            // Cannot create an annotation with zero length text anchor
            if (selection.IsEmpty)
            {
                throw new InvalidOperationException(SR.EmptySelectionNotSupported);
            }

            Nullable<Color> color = null;
            if (highlightBrush != null)
            {
                SolidColorBrush brush = highlightBrush as SolidColorBrush;
                if (brush == null)
                    throw new ArgumentException(SR.InvalidHighlightColor, nameof(highlightBrush));

                // Opacity less than 0 is treated as 0; greater than 1 is treated a 1.
                byte alpha;
                if (brush.Opacity <= 0)
                    alpha = 0;
                else if (brush.Opacity >= 1)
                    alpha = brush.Color.A;
                else
                    alpha = (byte) (brush.Opacity * brush.Color.A);

                color = Color.FromArgb(alpha, brush.Color.R, brush.Color.G, brush.Color.B);
            }

            // Create a range so we can move its ends without changing the selection
            ITextRange anchor = new TextRange(selection.Start, selection.End);

            Annotation highlight = ProcessHighlights(service, anchor, author, color, create);

View on GitHub (pinned to 81131a70a4)