cefsharp/CefSharp · error · Exception

UnRegisterResourceHandler can only be used with the default

Error message

UnRegisterResourceHandler can only be used with the default IResourceRequestHandlerFactory(DefaultResourceRequestHandlerFactory) implementation

What it means

UnRegisterResourceHandler is a convenience extension that only works against the built-in ResourceRequestHandlerFactory, because it simply removes a URL entry from that factory's internal handler map. The code casts browser.ResourceRequestHandlerFactory to ResourceRequestHandlerFactory; if you supplied your own IResourceRequestHandlerFactory implementation, the cast returns null and the method refuses to operate on an unknown store.

Source

Thrown at CefSharp/WebBrowserExtensions.cs:1031

            }
        }

        /// <summary>
        /// Unregister a ResourceHandler. Can only be used when browser.ResourceHandlerFactory is an instance of
        /// DefaultResourceHandlerFactory.
        /// </summary>
        /// <exception cref="Exception">Thrown when an exception error condition occurs.</exception>
        /// <param name="browser">The ChromiumWebBrowser instance this method extends.</param>
        /// <param name="url">the url of the resource to unregister.</param>
        public static void UnRegisterResourceHandler(this IWebBrowser browser, string url)
        {
            ThrowExceptionIfChromiumWebBrowserDisposed(browser);

            var handler = browser.ResourceRequestHandlerFactory as ResourceRequestHandlerFactory;

            if (handler == null)
            {
                throw new Exception("UnRegisterResourceHandler can only be used with the default IResourceRequestHandlerFactory(DefaultResourceRequestHandlerFactory) implementation");
            }

            handler.UnregisterHandler(url);
        }

        /// <summary>
        /// Stops loading the current page.
        /// </summary>
        /// <param name="browser">The ChromiumWebBrowser instance this method extends.</param>
        public static void Stop(this IChromiumWebBrowserBase browser)
        {
            ThrowExceptionIfChromiumWebBrowserDisposed(browser);

            browser.BrowserCore.Stop();
        }

        /// <summary>
        /// Stops loading the current page.

View on GitHub (pinned to 16bc6e0711)

Solutions

If you only need default behavior, do not set a custom factory; let CefSharp assign the default ResourceRequestHandlerFactory (or assign new ResourceRequestHandlerFactory() yourself).
If you must keep a custom IResourceRequestHandlerFactory, manage your own handler registry and unregister there instead of calling UnRegisterResourceHandler.
Check the type before calling: only invoke UnRegisterResourceHandler when browser.ResourceRequestHandlerFactory is ResourceRequestHandlerFactory.
Use RegisterResourceHandler/LoadHtml counterparts consistently; they share the same default-factory requirement.

Example fix

// before
browser.ResourceRequestHandlerFactory = new MyCustomFactory();
...
browser.UnRegisterResourceHandler(url); // throws

// after (option A): keep default factory
// do not assign a custom factory; UnRegisterResourceHandler works
browser.UnRegisterResourceHandler(url);

// after (option B): custom factory - unregister in your own implementation
((MyCustomFactory)browser.ResourceRequestHandlerFactory).Unregister(url);

Defensive patterns

Strategy: type-guard

Validate before calling

var factory = browser?.ResourceRequestHandlerFactory;
if (factory is ResourceRequestHandlerFactory)
{
    browser.UnRegisterResourceHandler(url);
}

Type guard

static bool UsesDefaultFactory(IWebBrowser browser) =>
    browser?.ResourceRequestHandlerFactory is ResourceRequestHandlerFactory;

Prevention

Decide upfront: either use the default ResourceRequestHandlerFactory for the convenience APIs or implement a custom factory and manage handlers yourself.
Avoid mixing custom factory assignment with Register/UnRegister/LoadHtml helpers.
Centralize handler registration in one place that knows which factory type is in use.

When it happens

Trigger: Calling browser.UnRegisterResourceHandler(url) after you previously assigned a custom class implementing IResourceRequestHandlerFactory to browser.ResourceRequestHandlerFactory (instead of the default ResourceRequestHandlerFactory). The 'as' cast at WebBrowserExtensions.cs:1027 yields null, tripping the guard.

Common situations: Apps that set a custom IResourceRequestHandlerFactory for fine-grained request interception/control, then try to use the high-level Register/UnRegister/LoadHtml helpers that assume the default factory. Copying sample code that mixes a custom factory with the convenience registration API.

Related errors

AI-assisted analysis of cefsharp/CefSharp@16bc6e0711 (2026-08-13). Data as JSON: /api/errors/47eee2ea72f889af. Report an issue: GitHub.