dotnet/wpf · error · InvalidEnumArgumentException

InvalidEnumArgumentException("captureMode"…

Error message

InvalidEnumArgumentException("captureMode", (int)captureMode, typeof(CaptureMode))

What it means

MouseDevice.Capture throws System.ComponentModel.InvalidEnumArgumentException when captureMode is not one of CaptureMode.None, CaptureMode.Element, or CaptureMode.SubTree. WPF explicitly validates the enum before processing the capture request.

Solutions

Validate with Enum.IsDefined(typeof(CaptureMode), value) before calling Capture
Only pass the named CaptureMode members (None/Element/SubTree)
Fix the serialization/deserialization path that produced the invalid value

Example fix

// before
mouse.Capture(target, (CaptureMode)savedInt); // throws on bad value
// after
CaptureMode mode = Enum.IsDefined(typeof(CaptureMode), savedInt)
    ? (CaptureMode)savedInt
    : CaptureMode.Element;
mouse.Capture(target, mode);

Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(CaptureMode), (int)captureMode))
    throw new InvalidEnumArgumentException(nameof(captureMode), (int)captureMode, typeof(CaptureMode));
mouse.Capture(element, captureMode);

Type guard

static bool IsValidCaptureMode(CaptureMode m) =>
    m == CaptureMode.None || m == CaptureMode.Element || m == CaptureMode.SubTree;

Try / catch

try { mouse.Capture(element, captureMode); }
catch (InvalidEnumArgumentException) { mouse.Capture(element, CaptureMode.Element); }

Prevention

Only pass literal CaptureMode.None/Element/SubTree
Validate deserialized CaptureMode values with Enum.IsDefined
Do not bitwise-combine CaptureMode values

When it happens

Trigger: Calling mouse.Capture(element, (CaptureMode)badValue) with an undefined enum value, typically from an int cast, deserialization, or a computed flag combination.

Common situations: Persisting CaptureMode as an int in settings and casting back unchecked; passing a bitwise combination of CaptureMode values which the enum does not define.

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationCore/System/Windows/Input/MouseDevice.cs:282

        /// <summary>
        ///     Captures the mouse to a particular element.
        /// </summary>
        public bool Capture(IInputElement element)
        {
            return Capture(element, CaptureMode.Element);
        }

        /// <summary>
        ///     Captures the mouse to a particular element.
        /// </summary>
        public bool Capture(IInputElement element, CaptureMode captureMode)
        {
            int timeStamp = Environment.TickCount;
//             VerifyAccess();

            if (!(captureMode == CaptureMode.None || captureMode == CaptureMode.Element || captureMode == CaptureMode.SubTree))
            {
                throw new System.ComponentModel.InvalidEnumArgumentException("captureMode", (int)captureMode, typeof(CaptureMode));
            }

            if (element == null)
            {
                captureMode = CaptureMode.None;
            }

            if (captureMode == CaptureMode.None)
            {
                element = null;
            }

            // Validate that elt is either a UIElement, a ContentElement or a UIElement3D.
            DependencyObject eltDO = element as DependencyObject;
            if (eltDO != null && !InputElement.IsValid(element))
            {
                throw new InvalidOperationException(SR.Format(SR.Invalid_IInputElement, eltDO.GetType()));
            }

View on GitHub (pinned to 81131a70a4)