What causes "SR.Animation_UnrecognizedHandoffBehavior" in dotnet/wpf?

dotnet/wpf · error · ArgumentException

SR.Animation_UnrecognizedHandoffBehavior

Error message

SR.Animation_UnrecognizedHandoffBehavior

What it means

Thrown by ContentElement.ApplyAnimationClock when the handoffBehavior argument is not a defined value of the HandoffBehavior enum (checked via HandoffBehaviorEnum.IsDefined). The library only accepts SnapshotAndReplace and Compose; any other cast or out-of-range value throws ArgumentException.

Solutions

Pass only HandoffBehavior.SnapshotAndReplace or HandoffBehavior.Compose.
Validate with Enum.IsDefined(typeof(HandoffBehavior), value) before calling, or use Enum.TryParse.
Replace raw numeric casts of external data with a validated parse.
If the value comes from configuration, fix the config to a valid enum name.

Example fix

// before
var behavior = (HandoffBehavior)42;
el.ApplyAnimationClock(dp, clock, behavior);
// after
if (!Enum.IsDefined(typeof(HandoffBehavior), rawValue)) throw new ArgumentOutOfRangeException(nameof(rawValue));
var behavior = (HandoffBehavior)rawValue; // now guaranteed valid

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

bool IsValidHandoff(HandoffBehavior b) => b is HandoffBehavior.SnapshotAndReplace or HandoffBehavior.Compose;

Try / catch

try { el.ApplyAnimationClock(dp, clock, behavior); }
catch (ArgumentException) { behavior = HandoffBehavior.SnapshotAndReplace; el.ApplyAnimationClock(dp, clock, behavior); }

Prevention

Never cast raw ints to HandoffBehavior without Enum.IsDefined validation.
Use Enum.TryParse when reading the value from config or external data.
Prefer strongly-typed enum references over numeric literals in animation code.
Validate enum-typed settings at load time, before any animation calls.

When it happens

Trigger: Passing an undefined HandoffBehavior value, typically from an invalid cast like (HandoffBehavior)99, an uninitialized/und enum variable, or a config-parsed integer outside the enum range.

Common situations: Deserializing a handoff behavior from config or XAML-adjacent data with an out-of-range numeric value; refactors that renamed enum members but left stale numeric casts; interop code passing raw ints.

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/e67463a79a70c320. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationCore/System/Windows/Generated/ContentElement.cs:82

            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)