AvaloniaUI/Avalonia · error · ArgumentException

Key frame key {key} is less than the previous one

Error message

Key frame key {key} is less than the previous one

What it means

Thrown by KeyFrames<T>.Validate when a newly inserted key frame has a lower normalizedProgressKey than the last (highest) key already in the collection. Key frames must be added in non-decreasing time order so the animation can interpolate forward.

Source

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

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);
            Add(new KeyFrame<T>
            {

View on GitHub (pinned to 11c5427268)

Solutions

1. Insert key frames in ascending progress order.
2. Sort your frame data by progress key before inserting.
3. If you need a frame before the current last one, rebuild the animation from scratch in order.

Example fix

// before
anim.InsertKeyFrame(0.5f, mid);
anim.InsertKeyFrame(0.25f, early); // throws: 0.25 < 0.5
// after
anim.InsertKeyFrame(0.25f, early);
anim.InsertKeyFrame(0.5f, mid);

// ensure frames are in ascending key order before inserting
foreach (var f in frames.OrderBy(f => f.Key)) anim.InsertKeyFrame(f.Key, f.Value);

When it happens

Trigger: Inserting frames out of order, e.g. InsertKeyFrame(0.5f,...) followed by InsertKeyFrame(0.25f,...). The message includes the offending key value.

Common situations: Data-driven key frames sourced from an unsorted collection; inserting a 'starting' frame at 0 after already adding 0.5/1.0; loop that adds frames in reverse.

Related errors

• Key frame key
• 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/85b653a576bb9ee3. Report an issue: GitHub.