What causes "DelayBetweenIterations value cannot be negative." in AvaloniaUI/Avalonia?

Clamp DelayBetweenIterations to zero or a positive span before running the animation.

AvaloniaUI/Avalonia · error · InvalidOperationException

DelayBetweenIterations value cannot be negative.

Error message

DelayBetweenIterations value cannot be negative.

What it means

Thrown by AnimationInstance<T>.FetchProperties when the Animation.DelayBetweenIterations property is negative. This is the idle gap inserted between repeated iterations; Avalonia rejects negative values because the iteration scheduler assumes non-negative delays.

Source

Thrown at src/Avalonia.Base/Animation/AnimationInstance`1.cs:101

        {
            _easeFunc = _animation.Easing;

            _speedRatioPrev = _speedRatio;
            _speedRatio = _animation.SpeedRatio;
            if (_speedRatio < 0d)
                throw new InvalidOperationException("SpeedRatio value cannot be negative.");

            _initialDelay = _animation.Delay;
            if (_initialDelay < TimeSpan.Zero)
                throw new InvalidOperationException("Delay value cannot be negative.");

            _duration = _animation.Duration;
            if (_duration < TimeSpan.Zero)
                throw new InvalidOperationException("Duration value cannot be negative.");

            _iterationDelay = _animation.DelayBetweenIterations;
            if (_iterationDelay < TimeSpan.Zero)
                throw new InvalidOperationException("DelayBetweenIterations value cannot be negative.");

            if (_animation.IterationCount.RepeatType == IterationType.Many)
            {
                if (_animation.IterationCount.Value > long.MaxValue)
                    throw new InvalidOperationException("IterationCount value cannot be larger than long.MaxValue.");
                _iterationCount = (long)_animation.IterationCount.Value;
            }
            else
            {
                _iterationCount = null;
            }

            _playbackDirectionPrev = _playbackDirection;
            _playbackDirection = _animation.PlaybackDirection;
            _fillMode = _animation.FillMode;
        }

        protected override void Unsubscribed()

View on GitHub (pinned to 11c5427268)

Solutions

Clamp DelayBetweenIterations to zero or a positive span before running the animation.
Correct the binding/calculator that emits a negative iteration delay.
Leave DelayBetweenIterations at its default (TimeSpan.Zero) if you do not need inter-iteration gaps.

Example fix

// before
animation.DelayBetweenIterations = computedGap;

// after
animation.DelayBetweenIterations = computedGap < TimeSpan.Zero ? TimeSpan.Zero : computedGap;

Defensive patterns

Strategy: validation

Validate before calling

if (animation.DelayBetweenIterations < TimeSpan.Zero)
    animation.DelayBetweenIterations = TimeSpan.Zero;

Prevention

Default DelayBetweenIterations to TimeSpan.Zero unless inter-iteration gaps are intended.
Validate bound timing values at the model boundary.
Document which timing properties are non-negative.

When it happens

Trigger: Running an Animation with DelayBetweenIterations set to a negative TimeSpan; reached in FetchProperties when _animation.DelayBetweenIterations < TimeSpan.Zero.

Common situations: Setting DelayBetweenIterations from a computed or bound value that can go negative; confusing it with SpeedRatio or a signed offset; deserializing a config with a bad sign.

Related errors

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