dotnet/wpf · error · InvalidOperationException

Failed to initialize GestureRecognizer.

Error message

Failed to initialize GestureRecognizer.

What it means

NativeRecognizer's constructor calls CreateContext to create a ink-recognition context from the system gesture recognizer. If the native call returns a failed HRESULT it throws InvalidOperationException(SR.UnspecifiedGestureConstructionException) — 'Failed to initialize GestureRecognizer.' — deliberately without COM details, since nothing useful can be passed to managed callers.

Solutions

1. Install the Windows 'Ink and Handwriting Recognition' / Tablet PC optional features on the target machine.
2. Wrap GestureRecognizer construction in try/catch for InvalidOperationException and degrade gracefully (disable gesture recognition) when unavailable.
3. Detect recognizer availability before use and hide/disable ink-gesture UI accordingly.
4. Repair/verify the Windows ink components (sfc /scannow, reinstall the ink feature) if they are corrupted.

Example fix

// before
var recognizer = new GestureRecognizer(); // InvalidOperationException on systems without ink recognizers
// after
GestureRecognizer recognizer = null;
try
{
    recognizer = new GestureRecognizer();
}
catch (InvalidOperationException)
{
    // ink recognition unavailable: fall back to no gesture support
}

static bool InkRecognizersAvailable()
{
    try { using var g = new GestureRecognizer(); return true; }
    catch (InvalidOperationException) { return false; }
}

static GestureRecognizer TryCreateRecognizer() =>
    OperatingSystem.IsWindows() ? ProbeRecognizer() : null;

try { recognizer = new GestureRecognizer(); }
catch (InvalidOperationException)
{
    recognizer = null;
    DisableGestureFeatures(); // degrade gracefully
}

When it happens

Trigger: Constructing a GestureRecognizer (which creates NativeRecognizer) on a machine where the ink recognition native components are missing or failed — e.g. Windows features 'Ink and Handwriting Recognition' not installed, a corrupted Tablet PC/ink stack, or CreateContext returning an error HRESULT.

Common situations: Server SKUs or stripped-down Windows installations without the handwriting/ink recognizer features; running in environments (containers, services, virtualized sessions) lacking the Tablet PC runtime; WPF apps using gesture recognition on systems where the recognizer DLLs fail to load.

Related errors

• Failed to set enabled gestures.
• Gesture recognition failed.
• ArgumentOutOfRangeException(nameof(oldProperty))
• ArgumentOutOfRangeException(nameof(percentageWithinBounds))
• ArgumentOutOfRangeException(nameof(percentageWithinLasso))

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationCore/MS/internal/Ink/GestureRecognizer/NativeRecognizer.cs:51

        /// </summary>
        static NativeRecognizer()
        {
            s_isSupported = LoadRecognizerDll();
        }

        /// <summary>
        /// Private constructor
        /// </summary>
        private NativeRecognizer()
        {
            Debug.Assert(NativeRecognizer.RecognizerHandleSingleton != null);

            int hr = MS.Win32.Recognizer.UnsafeNativeMethods.CreateContext(NativeRecognizer.RecognizerHandleSingleton,
                                                                        out _hContext);
            if (HRESULT.Failed(hr))
            {
                //don't throw a com exception here, we don't need to pass out any details
                throw new InvalidOperationException(SR.UnspecifiedGestureConstructionException);
            }

            // We add a reference of the recognizer to the context handle.
            // The context will dereference the recognizer reference when it gets disposed.
            // This trick will prevent the GC from disposing the recognizer before all contexts.
            _hContext.AddReferenceOnRecognizer(NativeRecognizer.RecognizerHandleSingleton);
        }

        #endregion Constructors

        //-------------------------------------------------------------------------------
        //
        // Internal Methods
        //
        //-------------------------------------------------------------------------------

        #region Internal Methods

View on GitHub (pinned to 81131a70a4)