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 WinForms ChromiumWebBrowser.BrowserSettings setter when the underlying CEF browser has already been instantiated. CefSharp creates the native browser lazily when the control's HWND handle is created (CreateBrowser sets the internal browserCreated flag), and once native creation begins the settings are frozen into CEF and can no longer be changed. Assigning BrowserSettings after that point is a programming error because it would have no effect.

Source

Thrown at CefSharp.WinForms/ChromiumWebBrowser.cs:126

            get
            {
                //We keep a reference to the browserSettings for the case where
                //the Control Handle is destroyed then Created see https://github.com/cefsharp/CefSharp/issues/2840
                //As it's not possible to change settings after the browser has been
                //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.

View on GitHub (pinned to 16bc6e0711)

Solutions

1. Set BrowserSettings in the constructor or immediately after `new ChromiumWebBrowser(...)`, before the control is added to any parent that would realize its handle.
2. If you must configure late, construct the browser with settings via the constructor overload or set the property before the form/control is shown (before Handle is created).
3. If configuration depends on runtime data known only at startup, build the IBrowserSettings instance first, then construct the ChromiumWebBrowser, then assign the pre-built settings immediately.
4. Verify you are not accidentally triggering handle creation (e.g. accessing .Handle, docking in a shown form) before assigning settings.

Example fix

// before
var browser = new ChromiumWebBrowser("about:blank");
this.Controls.Add(browser);
browser.BrowserSettings = new BrowserSettings { WindowlessFrameRate = 30 }; // throws: handle already created

// after
var browser = new ChromiumWebBrowser("about:blank");
browser.BrowserSettings = new BrowserSettings { WindowlessFrameRate = 30 };
this.Controls.Add(browser);

// BrowserSettings can only be set before the native browser is created.
// There is no public browserCreated flag; the safe rule is: assign before the control is parented/shown.
if (!browser.IsBrowserInitialized)
{
    browser.BrowserSettings = new BrowserSettings { WebGl = CefState.Disabled };
}

When it happens

Trigger: Assigning the BrowserSettings property after the WinForms control handle has been created. This happens when the control has been added to a visible Form (Handle created), after OnHandleCreated/CreateBrowser has run, or on a handle recreation (RecreatingHandle) where the browser was already initialized.

Common situations: Setting BrowserSettings in Form.Load or a later event instead of right after `new ChromiumWebBrowser()`; assigning it after calling Load() or after the form is shown; reusing a control whose handle was already created; designer-hosted controls whose handles are created early.

Related errors

• BrowserSettings 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
• IBrowser instance is null. Browser has likely not finished i

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