{"record":{"id":"ff9ae35f4e1a7f1a","repo":"cefsharp/CefSharp","slug":"screenshotornull-and-screenshotasync-can-only-be-u","errorCode":null,"errorMessage":"ScreenshotOrNull and ScreenshotAsync can only be used in combination with the DefaultRenderHandler","messagePattern":"ScreenshotOrNull and ScreenshotAsync can only be used in combination with the DefaultRenderHandler","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"CefSharp.OffScreen/ChromiumWebBrowser.cs","lineNumber":489,"sourceCode":"        /// only start this task once your page is loaded (which you can detect via FrameLoadEnd\n        /// or your own heuristics based on evaluating JavaScript).\n        /// It is your responsibility to dispose the returned Bitmap.\n        /// The bitmap size is determined by the Size property set earlier.\n        /// </summary>\n        /// <param name=\"blend\">Choose which bitmap to retrieve, choose <see cref=\"PopupBlending.Blend\"/> for a merged bitmap.</param>\n        /// <returns>Bitmap.</returns>\n        public Bitmap ScreenshotOrNull(PopupBlending blend = PopupBlending.Main)\n        {\n            if (RenderHandler == null)\n            {\n                throw new NullReferenceException(\"RenderHandler cannot be null. Use DefaultRenderHandler unless implementing your own\");\n            }\n\n            var renderHandler = RenderHandler as DefaultRenderHandler;\n\n            if (renderHandler == null)\n            {\n                throw new Exception(\"ScreenshotOrNull and ScreenshotAsync can only be used in combination with the DefaultRenderHandler\");\n            }\n\n            lock (renderHandler.BitmapLock)\n            {\n                if (blend == PopupBlending.Main)\n                {\n                    return renderHandler.BitmapBuffer.CreateBitmap();\n                }\n\n                if (blend == PopupBlending.Popup)\n                {\n                    return renderHandler.PopupOpen ? renderHandler.PopupBuffer.CreateBitmap() : null;\n                }\n\n\n                var bitmap = renderHandler.BitmapBuffer.CreateBitmap();\n\n                if (renderHandler.PopupOpen && bitmap != null)","sourceCodeStart":471,"sourceCodeEnd":507,"githubUrl":"https://github.com/cefsharp/CefSharp/blob/16bc6e0711a4945be17e8bc4bc7ccf9469f3fdec/CefSharp.OffScreen/ChromiumWebBrowser.cs#L471-L507","documentation":"Thrown by ScreenshotOrNull when RenderHandler is non-null but is not a DefaultRenderHandler. The screenshot methods read DefaultRenderHandler.BitmapBuffer/PopupBuffer directly via a cast, so a custom IRenderHandler implementation cannot supply the expected bitmap buffer shape. The cast fails and the exception directs users to DefaultRenderHandler.","triggerScenarios":"Assigning a custom IRenderHandler implementation to ChromiumWebBrowser.RenderHandler and then calling ScreenshotOrNull or ScreenshotAsync.","commonSituations":"Implementing a custom render handler for headless rendering pipelines and expecting ScreenshotOrNull to still work.","solutions":["Use DefaultRenderHandler if you need ScreenshotOrNull/ScreenshotAsync.","If you must use a custom render handler, capture the bitmap yourself from OnPaint and do not use these screenshot methods.","Subclass DefaultRenderHandler to add custom behavior while keeping screenshot compatibility."],"exampleFix":"// before\nbrowser.RenderHandler = new MyCustomRenderHandler();\nvar bmp = browser.ScreenshotOrNull(); // throws\n\n// after\nbrowser.RenderHandler = new DefaultRenderHandler(browser);\nvar bmp = browser.ScreenshotOrNull();","handlingStrategy":"type-guard","validationCode":"if (!(browser.RenderHandler is DefaultRenderHandler)) browser.RenderHandler = new DefaultRenderHandler(browser);\nvar bmp = browser.ScreenshotOrNull();","typeGuard":"public static bool HasDefaultRenderHandler(ChromiumWebBrowser b) => b.RenderHandler is DefaultRenderHandler;","tryCatchPattern":"try { return browser.ScreenshotOrNull(); }\ncatch (Exception ex) when (ex.Message.Contains(\"DefaultRenderHandler\")) { /* use CaptureScreenshotAsync or assign default */ }","preventionTips":["Use DefaultRenderHandler if you rely on ScreenshotOrNull/ScreenshotAsync.","Subclass DefaultRenderHandler rather than implementing IRenderHandler from scratch.","For custom renderers, capture the bitmap yourself from OnPaint."],"tags":["offscreen","render-handler","screenshot","type-mismatch"],"backgroundTag":null,"analyzedSha":"16bc6e0711a4945be17e8bc4bc7ccf9469f3fdec","analyzedAt":"2026-08-13T19:57:05.828Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}