{"record":{"id":"69e0bfc315d95789","repo":"dotnet/wpf","slug":"sr-storyboard-unrecognizedhandoffbehavior","errorCode":null,"errorMessage":"SR.Storyboard_UnrecognizedHandoffBehavior","messagePattern":"SR\\.Storyboard_UnrecognizedHandoffBehavior","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/Media/Animation/Storyboard.cs","lineNumber":1215,"sourceCode":"        INameScope nameScope = null;\n        HandoffBehavior handoffBehavior = HandoffBehavior.SnapshotAndReplace;\n        bool isControllable =  true;\n        Int64 layer = Storyboard.Layers.Code;\n\n        BeginCommon(containingObject, nameScope, handoffBehavior, isControllable, layer);\n    }\n    \n    /// <summary>\n    ///     Begins all animations underneath this storyboard, clock tree starts at the given containing object.\n    /// </summary>\n    internal void BeginCommon( DependencyObject containingObject, INameScope nameScope,\n        HandoffBehavior handoffBehavior, bool isControllable, Int64 layer)\n    {\n        ArgumentNullException.ThrowIfNull(containingObject);\n\n        if (!HandoffBehaviorEnum.IsDefined(handoffBehavior))\n        {\n            throw new ArgumentException(SR.Storyboard_UnrecognizedHandoffBehavior);\n        }\n\n        if (BeginTime == null)\n        {\n            // a null BeginTime means to not allocate or start the clock\n            return;\n        }\n\n        // It's not possible to begin when there is no TimeManager.  This condition\n        //  is known to occur during app shutdown.  Since an app being shut down\n        //  won't care about its Storyboards, we silently exit.\n        // If we don't exit here, we'll need to catch and handle the \"no time\n        //  manager\" exception implemented for bug #1247862\n        if( MediaContext.CurrentMediaContext.TimeManager == null )\n        {\n            return;\n        }\n","sourceCodeStart":1197,"sourceCodeEnd":1233,"githubUrl":"https://github.com/dotnet/wpf/blob/81131a70a4c573cd62748a5c36908fc4d662daa9/src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/Media/Animation/Storyboard.cs#L1197-L1233","documentation":"Thrown by Storyboard's public Begin overload when the handoffBehavior argument is not a defined member of the HandoffBehavior enum. The library validates enum arguments with HandoffBehaviorEnum.IsDefined and rejects unknown values via ArgumentException before creating clocks.","triggerScenarios":"Calling Storyboard.Begin/Begin(containingObject, isControllable, handoffBehavior, ...) with a HandoffBehavior value outside 0..3, e.g. a cast of an uninitialized or bogus integer like (HandoffBehavior)99.","commonSituations":"Persisting the enum to config/database as a raw int and reading back a stale or out-of-range value; interop code computing the enum; .NET version differences introducing/garbling values.","solutions":["Pass one of the defined values: HandoffBehavior.SnapshotAndReplace, Compose, SnapshotAndReplace, or SnapshotAndReplace's siblings (SnapshotAndReplace, Compose are the valid members).","If the value comes from external input, validate it with Enum.IsDefined(typeof(HandoffBehavior), value) before passing it.","Fix serialization/deserialization of the enum (store as string, or clamp/validate on read)."],"exampleFix":"// before\nvar hb = (HandoffBehavior)storedInt; // may be out of range\nstoryboard.Begin(this, true, hb);\n// after\nvar hb = Enum.IsDefined(typeof(HandoffBehavior), storedInt) ? (HandoffBehavior)storedInt : HandoffBehavior.SnapshotAndReplace;\nstoryboard.Begin(this, true, hb);","handlingStrategy":"type-guard","validationCode":"bool valid = Enum.IsDefined(typeof(HandoffBehavior), handoffBehavior);\nif (!valid) handoffBehavior = HandoffBehavior.SnapshotAndReplace;","typeGuard":"bool IsValidHandoff(HandoffBehavior hb) => hb is HandoffBehavior.SnapshotAndReplace or HandoffBehavior.Compose;","tryCatchPattern":"try { sb.Begin(this, true, hb); }\ncatch (ArgumentException ex) when (ex.ParamName == null || ex.Message.Contains(\"Handoff\")) { sb.Begin(this, true, HandoffBehavior.SnapshotAndReplace); }","preventionTips":["Never cast raw ints to HandoffBehavior without Enum.IsDefined","Store enums as strings when persisting","Use the named enum members instead of casts"],"tags":["wpf","animation","enum","argument-exception","validation"],"backgroundTag":"invalid-enum-value","analyzedSha":"81131a70a4c573cd62748a5c36908fc4d662daa9","analyzedAt":"2026-09-14T10:12:48.479Z","contentChangedAt":"2026-09-14T10:12:48.479Z","schemaVersion":2},"datasetVersion":"2026-09-21T21:30:21.729Z"}