{"record":{"id":"d19263b0ef3ebf3f","repo":"cefsharp/CefSharp","slug":"iframe-instance-is-null-browser-has-likely-not-fi","errorCode":null,"errorMessage":"IFrame instance is null. Browser has likely not finished initializing or is in the process of disposing.","messagePattern":"IFrame instance is null\\. Browser has likely not finished initializing or is in the process of disposing\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"CefSharp/WebBrowserExtensions.cs","lineNumber":1974,"sourceCode":"            {\n                // Provide a more meaningful message for WinForms ChromiumHostControl\n                // should be ChromiumWebBrowser/ChromiumHostControl\n                var type = browser.GetType();\n\n                throw new ObjectDisposedException(type.Name);\n            }\n        }\n\n        /// <summary>\n        /// Throw exception if frame null.\n        /// </summary>\n        /// <exception cref=\"Exception\">Thrown when an exception error condition occurs.</exception>\n        /// <param name=\"frame\">The <seealso cref=\"IFrame\"/> instance this method extends.</param>\n        public static void ThrowExceptionIfFrameNull(IFrame frame)\n        {\n            if (frame == null)\n            {\n                throw new Exception(FrameNullExceptionString);\n            }\n        }\n\n        /// <summary>\n        /// An IBrowser extension method that throw exception if browser null.\n        /// </summary>\n        /// <exception cref=\"Exception\">Thrown when an exception error condition occurs.</exception>\n        /// <param name=\"browser\">The ChromiumWebBrowser instance this method extends.</param>\n        public static void ThrowExceptionIfBrowserNull(IBrowser browser)\n        {\n            if (browser == null)\n            {\n                throw new Exception(BrowserNullExceptionString);\n            }\n        }\n\n        /// <summary>\n        /// Throw exception if browser host null.","sourceCodeStart":1956,"sourceCodeEnd":1992,"githubUrl":"https://github.com/cefsharp/CefSharp/blob/16bc6e0711a4945be17e8bc4bc7ccf9469f3fdec/CefSharp/WebBrowserExtensions.cs#L1956-L1992","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Guard with a null check: var frame = browser.MainFrame; if (frame != null) { ... }.","Avoid calling frame methods from disposing/closed event handlers.","Use IsBrowserInitialized before any frame-touching call."],"exampleFix":"// before\nvar frame = browser.MainFrame;\nframe.ExecuteJavaScriptAsync(\"alert(1)\"); // MainFrame null -> throws\n\n// after\nvar frame = browser.MainFrame;\nif (frame != null)\n{\n    frame.ExecuteJavaScriptAsync(\"alert(1)\");\n}","handlingStrategy":"validation","validationCode":"var frame = browser.MainFrame;\nif (frame != null)\n{\n    frame.ExecuteJavaScriptAsync(script);\n}","typeGuard":"static bool HasMainFrame(IBrowser browser) => browser?.MainFrame != null;","tryCatchPattern":null,"preventionTips":["Defer frame access until FrameLoadEnd or LoadingStateChanged(IsLoading == false).","Null-check frames captured from popups/sub-frames before use.","Do not touch frames from disposing handlers."],"tags":["cefsharp","frame","lifecycle","initialization"],"backgroundTag":null,"analyzedSha":"16bc6e0711a4945be17e8bc4bc7ccf9469f3fdec","analyzedAt":"2026-08-13T19:57:05.828Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}