cefsharp/CefSharp · error · Exception

The ChromiumWebBrowser instance creates the underlying Chrom

Error message

The ChromiumWebBrowser instance creates the underlying Chromium Embedded Framework (CEF) browser instance in an async fashion. The undelying CefBrowser instance is not yet initialized. Use the IsBrowserInitializedChanged event and check the IsBrowserInitialized property to determine when the browser has been initialized.

What it means

The underlying CefBrowser instance is created asynchronously after the ChromiumWebBrowser control is constructed. Any API that needs the live browser (screenshots, dev tools, script execution, navigation queries) calls ThrowExceptionIfBrowserNotInitialized, which checks an interlocked flag set only after CEF reports initialization complete.

Source

Thrown at CefSharp.Wpf/HwndHost/ChromiumWebBrowser.cs:1939

            }

            using (var devToolsClient = browser.GetDevToolsClient())
            {
                var screenShot = await devToolsClient.Page.CaptureScreenshotAsync(format, quality, viewPort, fromSurface, captureBeyondViewport).ConfigureAwait(continueOnCapturedContext: false);

                return screenShot.Data;
            }
        }

        /// <summary>
        /// Throw exception if browser not initialized.
        /// </summary>
        /// <exception cref="Exception">Thrown when an exception error condition occurs.</exception>
        private void ThrowExceptionIfBrowserNotInitialized()
        {
            if (!InternalIsBrowserInitialized())
            {
                throw new Exception(BrowserNotInitializedExceptionErrorMessage);
            }
        }

        /// <summary>
        /// Throw exception if disposed.
        /// </summary>
        /// <exception cref="ObjectDisposedException">Thrown when a supplied object has been disposed.</exception>
        private void ThrowExceptionIfDisposed()
        {
            if (IsDisposed)
            {
                throw new ObjectDisposedException("browser", "Browser has been disposed");
            }
        }

        private int GetChromiumChildProcessId(string frameIdentifier)
        {
            try

View on GitHub (pinned to 16bc6e0711)

Solutions

1. Subscribe to IsBrowserInitializedChanged and check IsBrowserInitialized before calling browser-dependent APIs.
2. Await the browser's initialization task (LoadUrlAsync or similar) before invoking further operations.
3. Guard every call with: if (browser.IsBrowserInitialized) { ... } else { /* wait or queue */ }.

Example fix

// before — throws because browser is not yet initialized
var browser = new ChromiumWebBrowser();
var shot = await browser.CaptureScreenshotAsync();

// after — wait for initialization
browser.IsBrowserInitializedChanged += async (s, e) =>
{
    if (browser.IsBrowserInitialized)
    {
        var shot = await browser.CaptureScreenshotAsync();
    }
};

if (!browser.IsBrowserInitialized)
{
    throw new InvalidOperationException(
        "Browser not initialized. Await IsBrowserInitializedChanged before calling this API.");
}
// safe to call browser-dependent API now

try
{
    var shot = await browser.CaptureScreenshotAsync();
}
catch (Exception ex) when (ex.Message.Contains("not yet initialized"))
{
    // Queue the operation for after initialization
    browser.IsBrowserInitializedChanged += async (s, e) =>
    {
        if (browser.IsBrowserInitialized)
            await browser.CaptureScreenshotAsync();
    };
}

When it happens

Trigger: Calling browser-dependent methods — CaptureScreenshotAsync, GetBrowser, EvaluateScriptAsync (on the HwndHost variant), PrintToPdfAsync, etc. — before IsBrowserInitialized is true.

Common situations: Trying to load a URL or take a screenshot immediately after `new ChromiumWebBrowser()`. Accessing the browser in a constructor or early Loaded handler without awaiting initialization.

Related errors

• IBrowser
• Browser has already been created. BrowserSettings must be se
• Browser has already been created. RequestContext must be set
• Unexpected failure of calling CEF->GetZoomLevelAsync
• Cef.IsInitialized was false!.Check the log file for errors!.

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