AvaloniaUI/Avalonia · error · FormatException

Invalid brush string: '{s}'.

Error message

Invalid brush string: '{s}'.

What it means

Brush.Parse throws a FormatException when the input string is neither a known color name nor a parseable color value. Brush.Parse first checks known colors, then attempts Color.TryParse; if both fail, the string is not a valid brush specification. Unlike WPF, Avalonia's Brush.Parse only accepts color representations (names, hex), not full brush syntax.

Source

Thrown at src/Avalonia.Base/Media/Brush.cs:88

            _ = s ?? throw new ArgumentNullException(nameof(s));

            if (s.Length > 0)
            {
                // Attempt to get a cached known brush first
                // This is a performance optimization for known colors
                var brush = KnownColors.GetKnownBrush(s);
                if (brush != null)
                {
                    return brush;
                }

                if (Color.TryParse(s, out Color color))
                {
                    return new ImmutableSolidColorBrush(color);
                }
            }

            throw new FormatException($"Invalid brush string: '{s}'.");
        }

        protected override void OnPropertyChanged(AvaloniaPropertyChangedEventArgs change)
        {
            if (change.Property == TransformProperty) 
                _resource.ProcessPropertyChangeNotification(change);

            RegisterForSerialization();

            base.OnPropertyChanged(change);
        }
        
        private protected void RegisterForSerialization() =>
            _resource.RegisterForInvalidationOnAllCompositors(this);

        private protected bool IsOnCompositor(Compositor c) => _resource.TryGetForCompositor(c) != null;

        private CompositorResourceHolder<ServerCompositionSimpleBrush> _resource;

View on GitHub (pinned to 11c5427268)

Solutions

  1. Validate the string with Color.TryParse before passing to Brush.Parse.
  2. Use a known color name or a valid hex string (#RGB, #RRGGBB, #AARRGGBB, #RRGGBBAA).
  3. If the string comes from config/user input, wrap in try-catch for FormatException or use TryParse patterns.

Example fix

// before
var brush = Brush.Parse(userInput);

// after
if (Color.TryParse(userInput, out var color))
    var brush = new ImmutableSolidColorBrush(color);
else
    // handle invalid input / show error
Defensive patterns

Strategy: validation

Validate before calling

if (Color.TryParse(s, out var color))
    brush = new ImmutableSolidColorBrush(color);
else
    brush = Brushes.Transparent; // or throw a domain-specific error

Try / catch

IBrush brush;
try { brush = Brush.Parse(s); }
catch (FormatException) { brush = Brushes.Transparent; }

Prevention

When it happens

Trigger: Calling Brush.Parse(s) with a malformed color string or an unrecognized token. Examples: "redd", "#GGG", "rgb(300,0,0)", or a XAML resource key that isn't a color.

Common situations: Typo in a color name in XAML/code. Passing a resource key or theme token instead of a color string. Misunderstanding that Brush.Parse accepts only color values, not gradient/gradient-brush syntax. Loading color strings from a config file with bad data.

Related errors

AI-assisted analysis of AvaloniaUI/Avalonia@11c5427268 (2026-08-13). Data as JSON: /api/errors/1f33e06dde14a946. Report an issue: GitHub.