AvaloniaUI/Avalonia · error · ArgumentException

Invalid KeySpline X2 value. Must be >= 0.0 and <= 1.0.

Error message

Invalid KeySpline X2 value. Must be >= 0.0 and <= 1.0.

What it means

Thrown by the ControlPointX2 setter when the supplied X2 value fails IsValidXValue (outside [0.0, 1.0]). Symmetric to the X1 case: the second control point's X must also stay normalized because it anchors the right side of the easing bezier's time axis.

Source

Thrown at src/Avalonia.Base/Animation/KeySpline.cs:138

            }
        }

        /// <summary>
        /// X coordinate of the second control point
        /// </summary>
        public double ControlPointX2
        {
            get => _controlPointX2;
            set
            {
                if (IsValidXValue(value))
                {
                    _controlPointX2 = value;
                    _isDirty = true;
                }
                else
                {
                    throw new ArgumentException("Invalid KeySpline X2 value. Must be >= 0.0 and <= 1.0.");
                }
            }
        }

        /// <summary>
        /// Y coordinate of the second control point
        /// </summary>
        public double ControlPointY2
        {
            get => _controlPointY2;
            set
            {
                _controlPointY2 = value;
                _isDirty = true;
            }
        }

        /// <summary>

View on GitHub (pinned to 11c5427268)

Solutions

1. Keep ControlPointX2 within 0.0 and 1.0 inclusive.
2. Clamp before assignment: Math.Clamp(v, 0.0, 1.0).
3. Express overshoot/bounce through Y1/Y2, not X2.

Example fix

// before
spline.ControlPointX2 = 2.0;

// after
spline.ControlPointX2 = 1.0;

double x2 = Math.Clamp(rawX2, 0.0, 1.0);
spline.ControlPointX2 = x2;

static bool IsValidX(double v) => double.IsFinite(v) && v >= 0.0 && v <= 1.0;

try { spline.ControlPointX2 = v; }
catch (ArgumentException) { spline.ControlPointX2 = Math.Clamp(v, 0.0, 1.0); }

When it happens

Trigger: Assigning a number outside [0,1] to KeySpline.ControlPointX2; building a curve like (0,0,2,1) where the second point's X overshoots.

Common situations: Mistakenly believing X2 can exceed 1 to model overshoot (overshoot is expressed via Y, not X); copy-pasting CSS cubic-bezier tuples with the wrong column.

Related errors

• {nameof(KeySpline)} must have X coordinates >= 0.0 and <= 1.
• Invalid KeySpline X1 value. Must be >= 0.0 and <= 1.0.
• Transition elements have different parents.
• No Setter property assigned.
• Unknown PlaybackBehavior value: {_playbackBehavior}

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