AvaloniaUI/Avalonia · error · ArgumentException

Key frame key

Error message

Key frame key

What it means

Thrown by KeyFrames<T>.Validate when a key frame's normalizedProgressKey is outside the [0,1] range. The terse message 'Key frame key' is unhelpful but means the progress key must be a normalized fraction (0 = start of animation, 1 = end).

Source

Thrown at src/Avalonia.Base/Rendering/Composition/Animations/KeyFrames.cs:18

using System;
using System.Collections.Generic;
using Avalonia.Animation.Easings;
using Avalonia.Rendering.Composition.Expressions;

namespace Avalonia.Rendering.Composition.Animations
{
    
    /// <summary>
    /// Collection of composition animation key frames
    /// </summary>
    /// <typeparam name="T"></typeparam>
    class KeyFrames<T> : List<KeyFrame<T>>, IKeyFrames
    {
        void Validate(float key)
        {
            if (key < 0 || key > 1)
                throw new ArgumentException("Key frame key");
            if (Count > 0 && this[Count - 1].NormalizedProgressKey > key)
                throw new ArgumentException("Key frame key " + key + " is less than the previous one");
        }
        
        public void InsertExpressionKeyFrame(float normalizedProgressKey, string value, IEasing easingFunction)
        {
            Validate(normalizedProgressKey);
            Add(new KeyFrame<T>
            {
                NormalizedProgressKey = normalizedProgressKey,
                Expression = Expression.Parse(value),
                EasingFunction = easingFunction
            });
        }

        public void Insert(float normalizedProgressKey, T value, IEasing easingFunction)
        {
            Validate(normalizedProgressKey);

View on GitHub (pinned to 11c5427268)

Solutions

1. Pass a normalized key in [0,1] (divide a percentage by 100).
2. Clamp: Math.Clamp(key, 0f, 1f).
3. Use InsertKeyFrame(1f, endValue) for the terminal frame.

Example fix

// before
anim.InsertKeyFrame(50f, value); // 50% passed as 50
// after
anim.InsertKeyFrame(0.5f, value);

float keyClamped = Math.Clamp(normalizedProgressKey, 0f, 1f);
anim.InsertKeyFrame(keyClamped, value);

static bool IsValidKey(float k) => k is >= 0f and <= 1f;

When it happens

Trigger: Calling InsertExpressionKeyFrame/InsertKeyFrame with a key like -0.1f, 1.5f, or passing a percentage (e.g. 50f instead of 0.5f).

Common situations: Passing a percent value (0..100) instead of a normalized value (0..1); sign error producing a negative; off-by-one where the last frame is keyed slightly above 1.

Related errors

• Key frame key {key} is less than the previous one
• Minimum allowed value is 1ms and maximum allowed value is 24
• Animation has no key frames
• Invalid animation duration
• Unknown property {propertyName}

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