dotnet/wpf · error · ArgumentException

SR.Storyboard_UnrecognizedHandoffBehavior (unrecognized…

Error message

SR.Storyboard_UnrecognizedHandoffBehavior (unrecognized HandoffBehavior value)

What it means

BeginStoryboard.HandoffBehavior throws ArgumentException with SR.Storyboard_UnrecognizedHandoffBehavior when the setter receives a value not defined in the HandoffBehavior enum. Only SnapshotAndReplace and Compose are accepted; any out-of-range cast value fails HandoffBehaviorEnum.IsDefined.

Solutions

Use only HandoffBehavior.SnapshotAndReplace or HandoffBehavior.Compose.
Validate any dynamically obtained value with Enum.IsDefined(typeof(HandoffBehavior), value) before assigning.
Fix the XAML attribute to a valid enum name if set from markup.

Example fix

// before
beginStoryboard.HandoffBehavior = (HandoffBehavior)userValue;
// after
var behavior = (HandoffBehavior)Enum.Parse(typeof(HandoffBehavior), userString);
if (!Enum.IsDefined(typeof(HandoffBehavior), behavior)) behavior = HandoffBehavior.SnapshotAndReplace;
beginStoryboard.HandoffBehavior = behavior;

Defensive patterns

Strategy: type-guard

Validate before calling

if (!Enum.IsDefined(typeof(HandoffBehavior), value))
    throw new ArgumentException($"Invalid HandoffBehavior: {value}");

Type guard

bool IsValidHandoffBehavior(object v) => v is HandoffBehavior hb && Enum.IsDefined(typeof(HandoffBehavior), hb);

Try / catch

try { beginStoryboard.HandoffBehavior = behavior; }
catch (ArgumentException ex) { beginStoryboard.HandoffBehavior = HandoffBehavior.SnapshotAndReplace; }

Prevention

Only assign enum members, never raw casts of external integers
Use Enum.TryParse when converting strings from XAML/config to HandoffBehavior
Prefer HandoffBehavior.SnapshotAndReplace as the default

When it happens

Trigger: Assigning an invalid value to BeginStoryboard.HandoffBehavior, typically via an unchecked cast like (HandoffBehavior)99 or bad XAML markup extension output, during property set on the BeginStoryboard object.

Common situations: XAML with a malformed HandoffBehavior attribute value, or programmatic animation setup where a variable of the wrong value is cast to HandoffBehavior.

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/Media/Animation/BeginStoryboard.cs:80

    /// </summary>
    [DefaultValue(HandoffBehavior.SnapshotAndReplace)]
    public HandoffBehavior HandoffBehavior 
    {
        get
        {
            return _handoffBehavior;
        }
        set
        {
            ThrowIfSealed();

            if(HandoffBehaviorEnum.IsDefined(value)) 
            {
                _handoffBehavior = value;
            }
            else
            {
                throw new ArgumentException(SR.Storyboard_UnrecognizedHandoffBehavior);
            }
        }
    }

    /// <summary>
    ///     The name to use for referencing this Storyboard.  This named is used 
    /// by a control action such as pause and resume.  Defaults to null, which
    /// means this storyboard is not going to be interactively controlled.
    /// </summary>
    // Null == no interactive control == "Fire and Forget"
    [DefaultValue(null)]
    public string Name
    {
        get
        {
            return _name;
        }
        set

View on GitHub (pinned to 81131a70a4)