{"record":{"id":"4a9fa6f76bfea5a4","repo":"dotnet/wpf","slug":"sr-handlertypeillegal-elements","errorCode":null,"errorMessage":"SR.HandlerTypeIllegal","messagePattern":"SR\\.HandlerTypeIllegal","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/Microsoft.DotNet.Wpf/src/WpfGfx/codegen/mcg/generators/Elements.cs","lineNumber":382,"sourceCode":"                    /// </param>\n                    /// <param name=\"handledEventsToo\">\n                    ///     Flag indicating whether or not the listener wants to\n                    ///     hear about events that have already been handled\n                    /// </param>\n                    public void AddHandler(\n                        RoutedEvent routedEvent,\n                        Delegate handler,\n                        bool handledEventsToo)\n                    {\n                        // VerifyAccess();\n\n                        ArgumentNullException.ThrowIfNull(routedEvent);\n\n                        ArgumentNullException.ThrowIfNull(handler);\n\n                        if (!routedEvent.IsLegalHandler(handler))\n                        {\n                            throw new ArgumentException(SR.HandlerTypeIllegal);\n                        }\n\n                        EnsureEventHandlersStore();\n                        EventHandlersStore.AddRoutedEventHandler(routedEvent, handler, handledEventsToo);\n\n                        OnAddHandler(routedEvent, handler);\n                    }\n\n                    /// <summary>\n                    ///     Notifies subclass of a new routed event handler.  Note that this is\n                    ///     called once for each handler added, but OnRemoveHandler is only called\n                    ///     on the last removal.\n                    /// </summary>\n                    internal virtual void OnAddHandler(\n                        RoutedEvent routedEvent,\n                        Delegate handler)\n                    {\n                    }","sourceCodeStart":364,"sourceCodeEnd":400,"githubUrl":"https://github.com/dotnet/wpf/blob/81131a70a4c573cd62748a5c36908fc4d662daa9/src/Microsoft.DotNet.Wpf/src/WpfGfx/codegen/mcg/generators/Elements.cs#L364-L400","documentation":"AddHandler(RoutedEvent, Delegate) validates that the supplied handler's signature matches the routed event's handler type (RoutedEvent.IsLegalHandler). When the delegate type does not match what the event expects, ArgumentException(SR.HandlerTypeIllegal) is thrown before the handler is added to the EventHandlersStore.","triggerScenarios":"Calling UIElement.AddHandler (generated wrapper) with a delegate whose parameter/return signature does not match the RoutedEvent's HandlerType, e.g. attaching a MouseEventHandler to a Keyboard.KeyDownEvent.","commonSituations":"Copy-pasted handler registrations between similar events; refactors that changed a delegate type; wiring generated/late-bound events where the event-to-handler mapping was hand-typed.","solutions":["Match the handler type to the event: use RoutedEvent.HandlerType to create the correct delegate","Use the strongly-typed AddXXXHandler convenience method generated for the event instead of raw AddHandler","Verify with routedEvent.IsLegalHandler(handler) before calling AddHandler"],"exampleFix":"// before\nel.AddHandler(Keyboard.KeyDownEvent, new MouseEventHandler(OnMouse));\n// after\nel.AddHandler(Keyboard.KeyDownEvent, new KeyEventHandler(OnKey));","handlingStrategy":"validation","validationCode":"if (!routedEvent.IsLegalHandler(handler)) throw new ArgumentException($\"Handler type {handler.GetType()} is not legal for {routedEvent.Name} (expects {routedEvent.HandlerType}).\");","typeGuard":"bool IsLegalFor(RoutedEvent e, Delegate d) => e.IsLegalHandler(d);","tryCatchPattern":"try { el.AddHandler(evt, handler); } catch (ArgumentException ex) when (ex.Message.Contains(\"HandlerType\")) { /* fix delegate type */ }","preventionTips":["Prefer generated strongly-typed AddXXXHandler methods","Check RoutedEvent.HandlerType before constructing delegates","Keep handler signatures consistent across subscribe/unsubscribe"],"tags":["wpf","routed-events","argument-exception","type-mismatch"],"backgroundTag":"type-mismatch","analyzedSha":"81131a70a4c573cd62748a5c36908fc4d662daa9","analyzedAt":"2026-09-14T10:12:48.479Z","contentChangedAt":"2026-09-14T10:12:48.479Z","schemaVersion":2},"datasetVersion":"2026-09-22T01:17:13.364Z"}