dotnet/wpf · error · ArgumentException

SR.Animation_UnrecognizedHandoffBehavior

Error message

SR.Animation_UnrecognizedHandoffBehavior

What it means

Visual3D.ApplyAnimationClock validates the handoffBehavior argument against the HandoffBehaviorEnum. If the value is not a defined HandoffBehavior member (SnapshotAndReplace or Compose), an ArgumentException with Animation_UnrecognizedHandoffBehavior is thrown. Only the two enumerated handoff behaviors are accepted when applying an animation clock.

Solutions

  1. Pass a valid HandoffBehavior value: HandoffBehavior.SnapshotAndReplace or HandoffBehavior.Compose.
  2. Validate externally supplied enum values with Enum.IsDefined(typeof(HandoffBehavior), value) before passing them in.
  3. If the value comes from serialized config, map unknown values to a documented default explicitly.

Example fix

// before
visual.ApplyAnimationClock(dp, clock, (HandoffBehavior)behaviorInt);
// after
var behavior = Enum.IsDefined(typeof(HandoffBehavior), behaviorInt) ? (HandoffBehavior)behaviorInt : HandoffBehavior.SnapshotAndReplace;
visual.ApplyAnimationClock(dp, clock, behavior);
Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(HandoffBehavior), handoffBehavior))
{
    handoffBehavior = HandoffBehavior.SnapshotAndReplace; // safe default
}
visual.ApplyAnimationClock(dp, clock, handoffBehavior);

Type guard

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

Try / catch

try { visual.ApplyAnimationClock(dp, clock, behavior); }
catch (ArgumentException ex) when (ex.Message.Contains("HandoffBehavior")) { visual.ApplyAnimationClock(dp, clock, HandoffBehavior.SnapshotAndReplace); }

Prevention

When it happens

Trigger: Calling ApplyAnimationClock(dp, clock, handoffBehavior) with an out-of-range enum value — e.g. a raw cast like (HandoffBehavior)99, an uninitialized/unset enum, or a value marshaled from unmanaged/serialized data that was never validated.

Common situations: Enum values persisted to XAML/config or received over remoting and cast unchecked; arithmetic or default(int)=0 confusion when composing behavior flags; a HandoffBehavior variable never initialized to a valid member.

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationCore/System/Windows/Media3D/Generated/Visual3D.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)