cefsharp/CefSharp · error · Exception

ScreenshotOrNull and ScreenshotAsync can only be used in com

Error message

ScreenshotOrNull and ScreenshotAsync can only be used in combination with the DefaultRenderHandler

What it means

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.

Source

Thrown at CefSharp.OffScreen/ChromiumWebBrowser.cs:489

        /// only start this task once your page is loaded (which you can detect via FrameLoadEnd
        /// or your own heuristics based on evaluating JavaScript).
        /// It is your responsibility to dispose the returned Bitmap.
        /// The bitmap size is determined by the Size property set earlier.
        /// </summary>
        /// <param name="blend">Choose which bitmap to retrieve, choose <see cref="PopupBlending.Blend"/> for a merged bitmap.</param>
        /// <returns>Bitmap.</returns>
        public Bitmap ScreenshotOrNull(PopupBlending blend = PopupBlending.Main)
        {
            if (RenderHandler == null)
            {
                throw new NullReferenceException("RenderHandler cannot be null. Use DefaultRenderHandler unless implementing your own");
            }

            var renderHandler = RenderHandler as DefaultRenderHandler;

            if (renderHandler == null)
            {
                throw new Exception("ScreenshotOrNull and ScreenshotAsync can only be used in combination with the DefaultRenderHandler");
            }

            lock (renderHandler.BitmapLock)
            {
                if (blend == PopupBlending.Main)
                {
                    return renderHandler.BitmapBuffer.CreateBitmap();
                }

                if (blend == PopupBlending.Popup)
                {
                    return renderHandler.PopupOpen ? renderHandler.PopupBuffer.CreateBitmap() : null;
                }


                var bitmap = renderHandler.BitmapBuffer.CreateBitmap();

                if (renderHandler.PopupOpen && bitmap != null)

View on GitHub (pinned to 16bc6e0711)

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.

Example fix

// before
browser.RenderHandler = new MyCustomRenderHandler();
var bmp = browser.ScreenshotOrNull(); // throws

// after
browser.RenderHandler = new DefaultRenderHandler(browser);
var bmp = browser.ScreenshotOrNull();

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(browser.RenderHandler is DefaultRenderHandler)) browser.RenderHandler = new DefaultRenderHandler(browser);
var bmp = browser.ScreenshotOrNull();

Type guard

public static bool HasDefaultRenderHandler(ChromiumWebBrowser b) => b.RenderHandler is DefaultRenderHandler;

Try / catch

try { return browser.ScreenshotOrNull(); }
catch (Exception ex) when (ex.Message.Contains("DefaultRenderHandler")) { /* use CaptureScreenshotAsync or assign default */ }

Prevention

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.

When it happens

Trigger: Assigning a custom IRenderHandler implementation to ChromiumWebBrowser.RenderHandler and then calling ScreenshotOrNull or ScreenshotAsync.

Common situations: Implementing a custom render handler for headless rendering pipelines and expecting ScreenshotOrNull to still work.

Related errors

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