cefsharp/CefSharp · error · Exception

Browser has already been created. BrowserSettings must be se

Error message

Browser has already been created. BrowserSettings must be set before the underlying CEF browser is created.

What it means

Thrown by the WPF ChromiumWebBrowser.BrowserSettings setter when browserCreated is true. In WPF the native browser is created lazily (CreateBrowser sets browserCreated at line ~2039, typically when the control is loaded/its visual is rendered), after which settings are frozen into CEF. The WPF setter additionally disposes a previously AutoDispose settings instance, but only if creation has not yet occurred.

Source

Thrown at CefSharp.Wpf/ChromiumWebBrowser.cs:203

        }

        /// <summary>
        /// WPF Keyboard Handled forwards key events to the underlying browser
        /// </summary>
        public IWpfKeyboardHandler WpfKeyboardHandler { get; set; }

        /// <summary>
        /// Gets or sets the browser settings.
        /// </summary>
        /// <value>The browser settings.</value>
        public IBrowserSettings BrowserSettings
        {
            get { return browserSettings; }
            set
            {
                if (browserCreated)
                {
                    throw new Exception("Browser has already been created. BrowserSettings must be " +
                                        "set before the underlying CEF browser is created.");
                }

                //New instance is created in the constructor, if you use
                //xaml to initialize browser settings then it will also create a new
                //instance, so we dispose of the old one
                if (browserSettings != null && browserSettings.AutoDispose)
                {
                    browserSettings.Dispose();
                }

                browserSettings = value;
            }
        }
        /// <summary>
        /// Gets or sets the request context.
        /// </summary>
        /// <value>The request context.</value>

View on GitHub (pinned to 16bc6e0711)

Solutions

Set BrowserSettings before the control loads: in the constructor, in XAML via a property bound at construction, or immediately after `new ChromiumWebBrowser()` before adding to the visual tree.
If bound in XAML, ensure the source value is available at binding initialization (not loaded asynchronously later).
To change settings, recreate the ChromiumWebBrowser instance with the new settings rather than reassigning.
Avoid causing the visual to render (showing the window) before the assignment.

Example fix

// before
<wpf:ChromiumWebBrowser x:Name="Browser" Address="about:blank" Loaded="OnLoaded"/>
private void OnLoaded(...) { Browser.BrowserSettings = new BrowserSettings(); } // throws

// after
<wpf:ChromiumWebBrowser x:Name="Browser" Address="about:blank"/>
// in constructor, before window shown:
Browser.BrowserSettings = new BrowserSettings();

Defensive patterns

Strategy: validation

Validate before calling

// Assign before the WPF control loads.
if (!browser.IsBrowserInitialized)
{
    browser.BrowserSettings = new BrowserSettings();
}

Prevention

Set BrowserSettings in the constructor or right after `new ChromiumWebBrowser()`, before the control loads.
If binding in XAML, ensure the source value is present at binding init, not loaded asynchronously.
To change settings, recreate the browser instance.

When it happens

Trigger: Setting BrowserSettings after the WPF control has loaded (Loaded event fired) or after the underlying visual was rendered and CEF creation began; setting it in code-behind after the control is on screen; XAML/data-binding re-evaluation that reassigns settings post-load.

Common situations: Data-binding BrowserSettings in XAML to a property whose value arrives after the browser loaded; configuring settings in Window.Loaded; reusing a control instance across navigations and trying to change settings.

Related errors

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