AvaloniaUI/Avalonia · error · ArgumentException

{value} is not a valid value for '{property.Name}'.

Error message

{value} is not a valid value for '{property.Name}'.

What it means

ValueStore.SetValue<T>(StyledProperty<T>, value, priority) runs the property's ValidateValue validation delegate before storing; if it returns false the value is rejected with ArgumentException. This is Avalonia's per-property validation gate for styled properties, enforcing value invariants (ranges, non-null, custom rules) independent of coercion.

Source

Thrown at src/Avalonia.Base/PropertyStore/ValueStore.cs:204

            observer.Start(source);
            return observer;
        }

        public void ClearValue(AvaloniaProperty property)
        {
            if (TryGetEffectiveValue(property, out var effective) &&
                (effective.Priority == BindingPriority.LocalValue || effective.IsOverridenCurrentValue))
            {
                effective.IsOverridenCurrentValue = false;
                ReevaluateEffectiveValue(property, effective, ignoreLocalValue: true);
            }
        }

        public IDisposable? SetValue<T>(StyledProperty<T> property, T value, BindingPriority priority)
        {
            if (property.ValidateValue?.Invoke(value) == false)
            {
                throw new ArgumentException($"{value} is not a valid value for '{property.Name}'.");
            }

            if (priority != BindingPriority.LocalValue)
            {
                var frame = GetOrCreateImmediateValueFrame(property, priority, out _);
                var result = frame.AddValue(property, value);

                if (TryGetEffectiveValue(property, out var existing))
                {
                    var effective = (EffectiveValue<T>)existing;
                    effective.SetAndRaise(this, result, priority);
                }
                else
                {
                    var effectiveValue = CreateEffectiveValue(property);
                    AddEffectiveValue(property, effectiveValue);
                    effectiveValue.SetAndRaise(this, result, priority);
                }

View on GitHub (pinned to 11c5427268)

Solutions

1. Inspect the StyledProperty's ValidateValue delegate (or its XML doc / source) to learn the allowed value set and pass only valid values.
2. Clamp/coerce the value before assignment (e.g. Math.Max(0, value) for non-negative properties).
3. For bindings, add a validation/transform in the binding pipeline so invalid upstream values never reach SetValue.
4. If you own the property, widen ValidateValue or throw a more descriptive exception to aid debugging.

Example fix

// before
control.Width = -5; // ValidateValue returns false -> ArgumentException

// after
control.Width = Math.Max(0, width);

if (property.ValidateValue != null && !property.ValidateValue(value)) return;
control.SetValue(property, value);

bool IsValid<T>(StyledProperty<T> p, T v) => p.ValidateValue is null || p.ValidateValue(v);

try { control.SetValue(property, value); }
catch (ArgumentException ex) { /* log invalid value, keep previous */ }

When it happens

Trigger: Calling SetValue / the property setter (or a binding) with a value that the StyledProperty's ValidateValue callback evaluates to false. Also reachable via AvaloniaObject.SetValue overloads that funnel into this method.

Common situations: Setting a numeric property outside its allowed range (e.g. Width < 0, opacity outside 0..1), assigning null to a non-null property, or assigning a value that violates a custom ValidateValue rule a control author added.

Related errors

• Name may not be empty
• Duration value cannot be negative.
• DelayBetweenIterations value cannot be negative.
• IterationCount value cannot be larger than long.MaxValue.
• This cue object's value should be within or equal to 0.0 and

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