cefsharp/CefSharp · error · Exception

BrowserSettings can only be of type {0} or null

Error message

BrowserSettings can only be of type {0} or null

What it means

Thrown by the WinForms ChromiumWebBrowser.BrowserSettings setter when the assigned value, after UnWrap(), is not assignable to CefSharp.Core.BrowserSettings (the only concrete implementation CEF recognizes). CefSharp exposes IBrowserSettings as an interface but the native bridge requires the exact core type; a custom or mock IBrowserSettings whose UnWrap() returns a different type cannot be passed across the boundary. The message interpolates the expected type so you know which concrete class to use.

Source

Thrown at CefSharp.WinForms/ChromiumWebBrowser.cs:131

                //created, and changing browserSettings then creating a new handle will
                //give a subtle different user experience if you aren't expecting it we
                //return null here even though we still have a reference.
                if (browserCreated)
                {
                    return null;
                }
                return browserSettings;
            }
            set
            {
                if (browserCreated)
                {
                    throw new Exception("Browser has already been created. BrowserSettings must be " +
                                        "set before the underlying CEF browser is created.");
                }
                if (value != null && !Core.ObjectFactory.BrowserSetingsType.IsAssignableFrom(value.UnWrap().GetType()))
                {
                    throw new Exception(string.Format("BrowserSettings can only be of type {0} or null", Core.ObjectFactory.BrowserSetingsType));
                }
                browserSettings = value;
            }
        }
        /// <summary>
        /// Activates browser upon creation, the default value is false. Prior to version 73
        /// the default behaviour was to activate browser on creation (Equivalent of setting this property to true).
        /// To restore this behaviour set this value to true immediately after you create the <see cref="ChromiumWebBrowser"/> instance.
        /// https://github.com/chromiumembedded/cef/issues/1856
        /// </summary>
        public bool ActivateBrowserOnCreation { get; set; }
        /// <summary>
        /// Gets or sets the request context.
        /// </summary>
        /// <value>The request context.</value>
        [Browsable(false), DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden), DefaultValue(null)]
        public IRequestContext RequestContext
        {

View on GitHub (pinned to 16bc6e0711)

Solutions

1. Use `new CefSharp.Core.BrowserSettings()` (or the IBrowserSettings returned by ObjectFactory) rather than a custom implementation.
2. Ensure all CefSharp.* assemblies (CefSharp, CefSharp.Core, CefSharp.WinForms) are the same version so the BrowserSetingsType identity matches.
3. If you hold an IBrowserSettings reference, call its UnWrap() and confirm the result is the Core type before assigning.
4. Pass null instead of a foreign type if you only want defaults.

Example fix

// before
browser.BrowserSettings = myCustomSettings; // myCustomSettings.UnWrap() is a foreign type

// after
browser.BrowserSettings = new CefSharp.Core.BrowserSettings { WebGl = CefState.Disabled };

var settings = new BrowserSettings(); // the Core concrete type
if (settings.UnWrap() is CefSharp.Core.BrowserSettings)
{
    browser.BrowserSettings = settings;
}

static bool IsValidBrowserSettings(IBrowserSettings value)
    => value == null || value.UnWrap() is CefSharp.Core.BrowserSettings;

When it happens

Trigger: Assigning a custom IBrowserSettings implementation whose UnWrap() does not return a CefSharp.Core.BrowserSettings instance; passing a mock/stub from a unit test; passing an object from a different CefSharp major version whose internal type differs.

Common situations: Unit-testing with a hand-rolled IBrowserSettings; mixing assemblies from different CefSharp versions (the Core type identity differs); accidentally wrapping the settings in another proxy layer.

Related errors

• Browser has already been created. BrowserSettings must be se
• RequestContext can only be of type {0} or null
• Browser has already been created. RequestContext must be set
• IBrowser instance is no longer valid. Control.Handle was lik
• IBrowserHost is null, you've likely call this method before

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