dotnet/wpf · critical · InvalidOperationException

SR.WebBrowserNoCastToIWebBrowser2

Error message

SR.WebBrowserNoCastToIWebBrowser2

What it means

The WebBrowser's internal accessor throws InvalidOperationException (SR.WebBrowserNoCastToIWebBrowser2) when the hosted ActiveX/WebOC control exists but could not be cast to IWebBrowser2, so the underlying browser interface is unavailable after transitioning to the Running state.

Solutions

  1. Ensure the target machine has Internet Explorer components/MSHTML available (Enable-VBR / verify ieframe.dll registration).
  2. Verify the WebBrowser control is hosted in a real, loaded WPF visual tree (Window shown) before use.
  3. Check registry key HKLM\...\Internet Explorer\Main\FeatureControl\FEATURE_BROWSER_EMULATION for conflicts.
  4. Consider migrating to WebView2 (Microsoft.Web.WebView2.Wpf) since the legacy WebBrowser control is deprecated.
  5. Wrap access in try-catch (InvalidOperationException) and surface a clear environment error.

Example fix

// before
webBrowser.Navigate("https://example.com"); // may throw if IWebBrowser2 unavailable
// after
try { webBrowser.Navigate("https://example.com"); }
catch (InvalidOperationException ex)
{
    // log: legacy WebBrowser hosting failed; consider WebView2 fallback
}
Defensive patterns

Strategy: try-catch

Validate before calling

if (!Environment.OSVersion.Platform.Equals(PlatformID.Win32NT)) skip legacy WebBrowser; ensure control is in a loaded visual tree;

Try / catch

try { webBrowser.Navigate(url); } catch (InvalidOperationException ex) { Log(ex); UseWebView2Fallback(url); }

Prevention

When it happens

Trigger: Accessing WebBrowser members that require _axIWebBrowser2 (navigation, InvokeScript, etc.) when ActiveX hosting failed to initialize — e.g. broken IE/Edge-WebView2 runtime registration, hosting in an unsupported environment, or activation failure.

Common situations: IE11/MSHTML not installed or disabled on the machine; hosting WebBrowser in non-WPF-window contexts (offscreen, service); registry Feature Browser Emulation issues; OS updates removing legacy WebBrowser support.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/PresentationFramework/System/Windows/Controls/WebBrowser.cs:653

        [DebuggerBrowsable(DebuggerBrowsableState.Never)]
        internal UnsafeNativeMethods.IWebBrowser2 AxIWebBrowser2
        {
            get
            {
                if (_axIWebBrowser2 == null)
                {
                    ObjectDisposedException.ThrowIf(IsDisposed, this);

                    //This should call AttachInterfaces which will set this member variable
                    //We don't want to force the state to InPlaceActive yet since we don't
                    //have the parent handle yet.
                    TransitionUpTo(ActiveXHelper.ActiveXState.Running);
                }
                // We still don't have _axIWebBrowser2. Throw an exception.
                if (_axIWebBrowser2 == null)
                {
                    throw new InvalidOperationException(SR.WebBrowserNoCastToIWebBrowser2);
                }
                return _axIWebBrowser2;
            }
        }

        internal WebOCHostingAdaptor HostingAdaptor { get { return _hostingAdaptor; } }

        internal Stream DocumentStream
        {
            get
            {
                return _documentStream;
            }
            set
            {
                _documentStream = value;
            }
        }

View on GitHub (pinned to 81131a70a4)