dotnet/wpf · error · ArgumentException

Animation_UnrecognizedHandoffBehavior

Animation_UnrecognizedHandoffBehavior

Error message

SR.Animation_UnrecognizedHandoffBehavior (Animation_UnrecognizedHandoffBehavior)

What it means

The handoffBehavior argument to ApplyAnimationClock is not a defined AnimationClock value (only SnapshotAndReplace and Compose are valid). HandoffBehaviorEnum.IsDefined fails and an ArgumentException is thrown. The enum dictates how a new animation clock combines with any existing animation on the property.

Solutions

Pass HandoffBehavior.SnapshotAndReplace or HandoffBehavior.Compose explicitly.
Validate any int before casting: Enum.IsDefined(typeof(HandoffBehavior), value).
Fix serialization code to round-trip enum names (Enum.ToString/Enum.Parse) instead of raw integers.

Example fix

// before
var behavior = (HandoffBehavior)storedInt; // may be invalid
anim.ApplyAnimationClock(dp, clock, behavior);
// after
if (!Enum.IsDefined(typeof(HandoffBehavior), storedInt)) throw new InvalidDataException(...);
anim.ApplyAnimationClock(dp, clock, (HandoffBehavior)storedInt);

Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(HandoffBehavior), handoffBehavior))
    throw new InvalidEnumArgumentException(nameof(handoffBehavior), (int)handoffBehavior, typeof(HandoffBehavior));

Type guard

static bool IsValidHandoff(HandoffBehavior h) =>
    h == HandoffBehavior.SnapshotAndReplace || h == HandoffBehavior.Compose;

Try / catch

try { target.ApplyAnimationClock(dp, clock, behavior); }
catch (ArgumentException) { /* fall back to SnapshotAndReplace */ }

Prevention

Never cast raw ints to HandoffBehavior without Enum.IsDefined.
Serialize enums by name.
Expose only the two valid values in your API surface.

When it happens

Trigger: Passing an out-of-range integer cast to HandoffBehavior (e.g. (HandoffBehavior)42) or an uninitialized/defaulted enum value that is not one of the two defined members.

Common situations: Storing HandoffBehavior in config/database as an int and casting back; deserializing invalid enum values from XAML-generated or persisted state; typos in bindings producing default(HandoffBehavior)=0 is valid, so this usually appears only with explicit bad casts.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of dotnet/wpf@81131a70a4 (2026-09-14). Data as JSON: /api/errors/91b87f3e58fc4235. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationCore/System/Windows/Media/Animation/Generated/Animatable.cs:81

            AnimationClock clock,
            HandoffBehavior handoffBehavior)
        {
            ArgumentNullException.ThrowIfNull(dp);

            if (!AnimationStorage.IsPropertyAnimatable(this, dp))
            {
                throw new ArgumentException(SR.Format(SR.Animation_DependencyPropertyIsNotAnimatable, dp.Name, this.GetType()), nameof(dp));
            }

            if (clock != null
                && !AnimationStorage.IsAnimationValid(dp, clock.Timeline))
            {
                throw new ArgumentException(SR.Format(SR.Animation_AnimationTimelineTypeMismatch, clock.Timeline.GetType(), dp.Name, dp.PropertyType), nameof(clock));
            }

            if (!HandoffBehaviorEnum.IsDefined(handoffBehavior))
            {
                throw new ArgumentException(SR.Animation_UnrecognizedHandoffBehavior);
            }

            if (IsSealed)
            {
                throw new InvalidOperationException(SR.Format(SR.IAnimatable_CantAnimateSealedDO, dp, this.GetType()));
            }

            AnimationStorage.ApplyAnimationClock(this, dp, clock, handoffBehavior);
        }

        /// <summary>
        /// Starts an animation for a DependencyProperty. The animation will
        /// begin when the next frame is rendered.
        /// </summary>
        /// <param name="dp">
        /// The DependencyProperty to animate.
        /// </param>
        /// <param name="animation">

View on GitHub (pinned to 81131a70a4)