cefsharp/CefSharp · critical · InvalidOperationException

Cef.Initialize() failed.Check the log file see https://githu

Error message

Cef.Initialize() failed.Check the log file see https://github.com/cefsharp/CefSharp/wiki/Trouble-Shooting#log-file for details.

What it means

Thrown by InitializeCefInternal when Cef.IsInitialized is null (never initialized) and Cef.Initialize(new CefSettings()) returns false. A false return means CEF itself rejected the settings or could not start. The message points to the troubleshooting wiki and the log file, since the real reason is in CEF's debug log.

Source

Thrown at CefSharp/Internals/Partial/ChromiumWebBrowser.Partial.cs:526

            LoadHandler = null;
            KeyboardHandler = null;
            JsDialogHandler = null;
            DragHandler = null;
            DownloadHandler = null;
            MenuHandler = null;
            ResourceRequestHandlerFactory = null;
            RenderProcessMessageHandler = null;

            this.FreeDevToolsContext();
        }

        private static void InitializeCefInternal()
        {
            if (Cef.IsInitialized == null)
            {
                if (!Cef.Initialize(new CefSettings()))
                {
                    throw new InvalidOperationException(CefInitializeFailedErrorMessage);
                }
            }

            if (Cef.IsInitialized == false)
            {
                throw new InvalidOperationException(CefIsInitializedFalseErrorMessage);
            }
        }

        /// <summary>
        /// Check is browser is initialized
        /// </summary>
        /// <returns>true if browser is initialized</returns>
        private bool InternalIsBrowserInitialized()
        {
            // Use CompareExchange to read the current value - if disposeCount is 1, we set it to 1, effectively a no-op
            // Volatile.Read would likely use a memory barrier which I believe is unnecessary in this scenario
            return Interlocked.CompareExchange(ref browserInitialized, 0, 0) == 1;

View on GitHub (pinned to 16bc6e0711)

Solutions

Read the CEF log file (debug.log / location set in CefSettings.LogFile) for the precise failure.
Verify all CefSharp.* NuGet packages use the same version and that the build copies libcef.dll and the subprocess.
Set all path settings (BrowserSubProcessPath, LocalesDirPath, ResourcesDirPath, CachePath) to absolute paths.
Confirm write permissions and that the cache/log directory is not locked by another instance.
Check the matching CEF runtime (e.g. VC++ redistributable) is installed.

Example fix

// before
Cef.Initialize(new CefSettings { BrowserSubProcessPath = "CefSharp.BrowserSubprocess.exe" });

// after
var s = new CefSettings();
s.BrowserSubProcessPath = Path.Combine(baseDir, "CefSharp.BrowserSubprocess.exe");
s.LogFile = Path.Combine(baseDir, "debug.log");
s.LogSeverity = LogSeverity.Verbose;
Cef.Initialize(s);

Defensive patterns

Strategy: validation

Validate before calling

foreach (var p in new[] { settings.BrowserSubProcessPath, settings.LocalesDirPath, settings.ResourcesDirPath })
    if (!string.IsNullOrEmpty(p) && !Path.IsPathRooted(p))
        throw new InvalidOperationException("CEF path must be absolute: " + p);
// Ensure binaries exist:
if (!File.Exists(settings.BrowserSubProcessPath))
    throw new FileNotFoundException("BrowserSubProcessPath missing", settings.BrowserSubProcessPath);

Try / catch

try { var browser = new ChromiumWebBrowser(url); }
catch (InvalidOperationException ex) when (ex.Message.StartsWith("Cef.Initialize()"))
{ /* read debug.log; report native/dependency/config failure */ }

Prevention

Make all CefSettings paths absolute and anchored to the app base dir.
Keep all CefSharp.* package versions identical.
Enable Verbose logging and inspect the log file on first run.
Verify libcef.dll and the subprocess are copied to the output.

When it happens

Trigger: Invalid CefSettings (missing/relative paths, bad cache dir), wrong or missing BrowserSubProcessPath, missing native CEF binaries/runtime, incompatible CEF redist version, file permission issues on the cache/log directory.

Common situations: First-run setup missing dependencies; path settings not absolute; mismatch between CefSharp and CefSharp.WinForms/Wpf/OffScreen versions; missing VC++ runtime or libcef.dll; antivirus blocking subprocess.

Related errors

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