cefsharp/CefSharp · error · Exception

IBrowser instance is null. Browser has likely not finished i

Error message

IBrowser instance is null. Browser has likely not finished initializing or is in the process of disposing.

What it means

Thrown by ChromiumHostControl.GetMainFrame() when BrowserCore is null, using the shared BrowserNullExceptionString constant. BrowserCore is null before the browser has finished initializing and is set to null during Dispose. The method has no valid MainFrame to return in either state, so it fails fast rather than returning a null dereference downstream.

Source

Thrown at CefSharp.WinForms/Host/ChromiumHostControl.cs:270

        /// <inheritdoc/>
        public Task<WaitForNavigationAsyncResponse> WaitForNavigationAsync(TimeSpan? timeout = null, CancellationToken cancellationToken = default)
        {
            //WaitForNavigationAsync is actually a static method so that CefSharp.Wpf.HwndHost can reuse the code
            return CefSharp.WebBrowserExtensions.WaitForNavigationAsync(this, timeout, cancellationToken);
        }

        /// <summary>
        /// Returns the main (top-level) frame for the browser window.
        /// </summary>
        /// <returns> the main frame</returns>
        public IFrame GetMainFrame()
        {
            var browser = BrowserCore;

            if(browser == null)
            {
                throw new Exception(CefSharp.WebBrowserExtensions.BrowserNullExceptionString);
            }

            return browser.MainFrame;
        }

        /// <inheritdoc/>
        protected override void Dispose(bool disposing)
        {
            if (disposing)
            {
                var browserCore = BrowserCore;

                AddressChanged = null;
                ConsoleMessage = null;
                FrameLoadEnd = null;
                FrameLoadStart = null;
                LoadError = null;
                LoadingStateChanged = null;

View on GitHub (pinned to 16bc6e0711)

Solutions

1. Guard with `if (hostControl.BrowserCore != null)` before calling GetMainFrame().
2. Wait for IsBrowserInitialized (subscribe or await) before touching the main frame.
3. Cancel background work on dispose so GetMainFrame is never called after teardown.
4. Use the async extension methods (e.g. GetMainFrameAsync / WaitForNavigationAsync) which handle the null core case.

Example fix

// before
var frame = hostControl.GetMainFrame(); // throws if BrowserCore null
var src = frame.Url;

// after
if (hostControl.BrowserCore != null)
{
    var frame = hostControl.GetMainFrame();
    var src = frame.Url;
}

if (hostControl.BrowserCore != null)
{
    var frame = hostControl.GetMainFrame();
}

static bool IsCoreAlive(ChromiumHostControl c) => c?.BrowserCore != null;

When it happens

Trigger: Calling GetMainFrame() before IsBrowserInitialized is true; calling it after Dispose has nulled BrowserCore; calling from a teardown or closing path.

Common situations: Reaching for the main frame to execute script or get the URL during early startup; background tasks invoking GetMainFrame after the user closed the control; chaining GetMainFrame().ExecuteScriptAsync without a null guard.

Related errors

• Browser has already been created. BrowserSettings must be se
• 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
• BrowserSettings can only be of type {0} or null

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