AvaloniaUI/Avalonia · error · InvalidOperationException

Unknown PlaybackBehavior value: {_playbackBehavior}

Error message

Unknown PlaybackBehavior value: {_playbackBehavior}

What it means

Thrown by Animation.Apply when the PlaybackBehavior value does not match any of the known switch arms (Auto, Always, OnlyIfVisible). This is an exhaustive-switch guard: an unexpected/undefined enum value was assigned to the Animation.PlaybackBehavior property.

Source

Thrown at src/Avalonia.Base/Animation/Animation.cs:313

            return (newAnimatorInstances, subscriptions, animatesVisibility);
        }

        IDisposable IAnimation.Apply(Animatable control, IClock? clock, IObservable<bool> match, Action? onComplete,
            bool isManuallyStarted)
            => Apply(control, clock, match, onComplete, isManuallyStarted);

        /// <inheritdoc cref="IAnimation.Apply"/>
        internal IDisposable Apply(Animatable control, IClock? clock, IObservable<bool> match, Action? onComplete,
            bool isManuallyStarted = false)
        {
            var (animators, subscriptions, animatesVisibility) = InterpretKeyframes(control);

            var shouldPauseOnInvisible = _playbackBehavior switch
            {
                PlaybackBehavior.Auto => !(animatesVisibility || isManuallyStarted),
                PlaybackBehavior.Always => false,
                PlaybackBehavior.OnlyIfVisible => true,
                _ => throw new InvalidOperationException($"Unknown PlaybackBehavior value: {_playbackBehavior}"),
            };

            if (animators.Count == 1)
            {
                var subscription = animators[0].Apply(this, control, clock, match,
                    onComplete, shouldPauseOnInvisible);

                if (subscription is not null)
                {
                    subscriptions.Add(subscription);
                }
            }
            else
            {
                var completionTasks = onComplete != null ? new List<Task>() : null;
                foreach (IAnimator animator in animators)
                {
                    Action? animatorOnComplete = null;

View on GitHub (pinned to 11c5427268)

Solutions

1. Only use the defined PlaybackBehavior members (Auto, Always, OnlyIfVisible) — do not cast arbitrary integers.
2. Ensure the Avalonia runtime version matches the version that defines the PlaybackBehavior members you reference.
3. If deserializing PlaybackBehavior, validate the value with Enum.IsDefined before assignment.
4. Update Avalonia packages consistently across the solution to avoid enum drift.

Example fix

// before
anim.PlaybackBehavior = (PlaybackBehavior)42; // undefined -> throws

// after
anim.PlaybackBehavior = Enum.IsDefined(typeof(PlaybackBehavior), raw)
    ? (PlaybackBehavior)raw
    : PlaybackBehavior.Auto;

// validate the enum before assigning
if (!Enum.IsDefined(typeof(PlaybackBehavior), raw))
    throw new ArgumentOutOfRangeException(nameof(raw));
animation.PlaybackBehavior = (PlaybackBehavior)raw;

static bool IsValidPlaybackBehavior(int v) => Enum.IsDefined(typeof(PlaybackBehavior), v);

When it happens

Trigger: Assigning PlaybackBehavior an invalid enum value — typically by casting an out-of-range integer to PlaybackBehavior (e.g. (PlaybackBehavior)999), or by referencing a value added in a newer Avalonia version while running against an older runtime that lacks that case.

Common situations: Version mismatch between the XAML/code defining the animation and the Avalonia runtime; casting arbitrary ints to the enum; serialization/binding deserializing a numeric value into PlaybackBehavior that falls outside the defined range; reflection-based construction setting an undefined value.

Related errors

• Invalid value
• No Setter property assigned.
• SpeedRatio value cannot be negative.
• Delay value cannot be negative.
• Duration value cannot be negative.

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