AvaloniaUI/Avalonia · error · ArgumentNullException

KeyFrame value can't be null.

Error message

KeyFrame value can't be null.

What it means

Thrown by AnimatorKeyFrame.GetTypedValue<T>() when the key frame's Value is null. The method needs a concrete value to type-convert into the animator's target type T, so a null value is treated as an argument error.

Source

Thrown at src/Avalonia.Base/Animation/AnimatorKeyFrame.cs:66

            if (value is BindingBase binding)
            {
                return Bind(ValueProperty, binding, targetControl);
            }
            else
            {
                return Bind(ValueProperty, Observable.SingleValue(value).ToBinding(), targetControl);
            }
        }

        [RequiresUnreferencedCode(TrimmingMessages.TypeConversionRequiresUnreferencedCodeMessage)]
        public T GetTypedValue<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] T>()
        {
            var typeConv = TypeDescriptor.GetConverter(typeof(T));

            if (Value == null)
            {
                throw new ArgumentNullException($"KeyFrame value can't be null.");
            }
            if(Value is T typedValue)
            {
                return typedValue;
            }
            if (!typeConv.CanConvertTo(Value.GetType()))
            {
                throw new InvalidCastException($"KeyFrame value doesnt match property type.");
            }

            return (T)typeConv.ConvertTo(Value, typeof(T))!;
        }

        internal override void BuildDebugDisplay(StringBuilder builder, bool includeContent)
        {
            base.BuildDebugDisplay(builder, includeContent);
            DebugDisplayHelper.AppendOptionalValue(builder, nameof(Property), Property, includeContent);
            DebugDisplayHelper.AppendOptionalValue(builder, nameof(Cue), Cue, includeContent);

View on GitHub (pinned to 11c5427268)

Solutions

1. Provide a non-null Value on the AnimatorKeyFrame (via XAML setter or code).
2. Ensure any binding feeding the key frame Value never produces null (use FallbackValue).
3. Validate key frames for null Value before running the animation.

Example fix

// before
var kf = new AnimatorKeyFrame { Cue = new Cue(0d) }; // Value omitted

// after
var kf = new AnimatorKeyFrame { Cue = new Cue(0d), Value = 0d };

foreach (var kf in animator)
    if (kf.Value is null)
        throw new InvalidOperationException($"KeyFrame at {kf.Cue} has a null Value.");

static bool HasValue(AnimatorKeyFrame kf) => kf.Value is not null;

When it happens

Trigger: Calling GetTypedValue<T>() on an AnimatorKeyFrame whose Value property was never set or was explicitly set to null.

Common situations: XAML KeyFrame missing its value child/setter; binding a key frame value to a source that yielded null; programmatic key frame creation where Value was skipped.

Related errors

• KeyFrame value doesnt match property type.
• {item.DebugDisplay} must have a value of type {typeof(Transf
• You can only set either {nameof(KeyTime)} or {nameof(Cue)}.
• No Setter property assigned.
• Duration value cannot be negative.

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