cefsharp/CefSharp · error · Exception

IFrame instance is null. Browser has likely not finished ini

Error message

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

What it means

ThrowExceptionIfFrameNull is a guard invoked by several extension methods that need an IFrame (e.g. via browser.MainFrame). The FrameNullExceptionString message means the frame reference was null, which happens when the browser has not finished initializing or is in the middle of disposing - CEF exposes no valid main frame at that moment.

Source

Thrown at CefSharp/WebBrowserExtensions.cs:1974

            {
                // Provide a more meaningful message for WinForms ChromiumHostControl
                // should be ChromiumWebBrowser/ChromiumHostControl
                var type = browser.GetType();

                throw new ObjectDisposedException(type.Name);
            }
        }

        /// <summary>
        /// Throw exception if frame null.
        /// </summary>
        /// <exception cref="Exception">Thrown when an exception error condition occurs.</exception>
        /// <param name="frame">The <seealso cref="IFrame"/> instance this method extends.</param>
        public static void ThrowExceptionIfFrameNull(IFrame frame)
        {
            if (frame == null)
            {
                throw new Exception(FrameNullExceptionString);
            }
        }

        /// <summary>
        /// An IBrowser extension method that throw exception if browser null.
        /// </summary>
        /// <exception cref="Exception">Thrown when an exception error condition occurs.</exception>
        /// <param name="browser">The ChromiumWebBrowser instance this method extends.</param>
        public static void ThrowExceptionIfBrowserNull(IBrowser browser)
        {
            if (browser == null)
            {
                throw new Exception(BrowserNullExceptionString);
            }
        }

        /// <summary>
        /// Throw exception if browser host null.

View on GitHub (pinned to 16bc6e0711)

Solutions

1. Defer frame access until the frame is ready: subscribe to LoadingStateChanged or FrameLoadEnd and only act when IsLoading is false and the frame is valid.
2. Guard with a null check: var frame = browser.MainFrame; if (frame != null) { ... }.
3. Avoid calling frame methods from disposing/closed event handlers.
4. Use IsBrowserInitialized before any frame-touching call.

Example fix

// before
var frame = browser.MainFrame;
frame.ExecuteJavaScriptAsync("alert(1)"); // MainFrame null -> throws

// after
var frame = browser.MainFrame;
if (frame != null)
{
    frame.ExecuteJavaScriptAsync("alert(1)");
}

var frame = browser.MainFrame;
if (frame != null)
{
    frame.ExecuteJavaScriptAsync(script);
}

static bool HasMainFrame(IBrowser browser) => browser?.MainFrame != null;

When it happens

Trigger: Calling frame-dependent extension methods (ExecuteJavaScriptAsync, EvaluateScriptAsync, LoadHtml via frame, GetSource, etc.) when browser.MainFrame returns null - before the browser is initialized or while it is tearing down. Also when accessing a frame that was already closed.

Common situations: Running script or accessing the DOM immediately after constructing the browser, before LoadingStateChanged/FrameLoadEnd fires. Calling these methods from a disposed/closing handler. Accessing pop-up or sub-frames that have already navigated away.

Related errors

• CookieManager store is not initialized.
• RequestContext is null, unable to obtain cookie manager
• IBrowserHost instance is null. Browser has likely not finish
• IBrowser
• Unable to invoke ExecuteDevToolsMethod on CEF UI Thread.

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