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

Create the delegate as routedEvent.HandlerType (e.g. new KeyEventHandler(OnKey))

dotnet/wpf · error · ArgumentException

SR.HandlerTypeIllegal

Error message

SR.HandlerTypeIllegal

What it means

In EventManager.RegisterClassHandler, after verifying the class type, the handler delegate is validated with routedEvent.IsLegalHandler; an incompatible delegate type throws ArgumentException with SR.HandlerTypeIllegal. The handler's signature must match the routed event's declared HandlerType.

Solutions

Create the delegate as routedEvent.HandlerType (e.g. new KeyEventHandler(OnKey))
Check routedEvent.HandlerType before constructing the delegate
Use the correct event-specific handler delegate for the routed event

Example fix

// before
EventManager.RegisterClassHandler(typeof(UIElement), Keyboard.KeyDownEvent,
    new RoutedEventHandler(OnKeyDown), false);
// after
EventManager.RegisterClassHandler(typeof(UIElement), Keyboard.KeyDownEvent,
    new KeyEventHandler(OnKeyDown), false);

Defensive patterns

Strategy: validation

Validate before calling

if (routedEvent.IsLegalHandler(handler)) { EventManager.RegisterClassHandler(classType, routedEvent, handler, handledEventsToo); }

Type guard

bool IsLegalClassHandler(RoutedEvent e, Delegate h) => e != null && h != null && e.IsLegalHandler(h);

Try / catch

try { EventManager.RegisterClassHandler(typeof(UIElement), evt, handler, false); } catch (ArgumentException) { /* handler delegate type mismatch */ }

Prevention

Construct delegates with the event's HandlerType
Use event-specific handler types (KeyEventHandler, MouseButtonEventHandler, ...)
Type generic registration helpers against the correct delegate type

When it happens

Trigger: Calling RegisterClassHandler with a Delegate whose signature doesn't match routedEvent.HandlerType — e.g. a RoutedEventHandler for a keyboard event declared with KeyEventHandler, or a lambda cast to the wrong delegate type.

Common situations: Generic helper methods taking Delegate and passing through to RegisterClassHandler; copy-pasted registration lines across events with different handler types; refactors that change an event's handler type.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of dotnet/wpf@81131a70a4 (2026-09-14). Data as JSON: /api/errors/a51f4b3768f0bea6. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationCore/System/Windows/EventManager.cs:164

            Delegate handler,
            bool handledEventsToo)
        {
            ArgumentNullException.ThrowIfNull(classType);

            ArgumentNullException.ThrowIfNull(routedEvent);

            ArgumentNullException.ThrowIfNull(handler);

            if (!typeof(UIElement).IsAssignableFrom(classType) &&
                !typeof(ContentElement).IsAssignableFrom(classType) &&
                !typeof(UIElement3D).IsAssignableFrom(classType))
            {
                throw new ArgumentException(SR.ClassTypeIllegal);
            }
            
            if (!routedEvent.IsLegalHandler(handler))
            {
                throw new ArgumentException(SR.HandlerTypeIllegal);
            }
            
            GlobalEventManager.RegisterClassHandler(classType, routedEvent, handler, handledEventsToo);
        }

        /// <summary>
        ///     Returns <see cref="RoutedEvent"/>s 
        ///     that have been registered so far
        /// </summary>
        /// <remarks>
        ///     Also see 
        ///     <see cref="EventManager.RegisterRoutedEvent"/>
        ///     <para/>
        ///     <para/>
        ///
        ///     NOTE: There may be more 
        ///     <see cref="RoutedEvent"/>s registered later
        /// </remarks>

View on GitHub (pinned to 81131a70a4)