cefsharp/CefSharp · error · NullReferenceException

RenderHandler cannot be null. Use DefaultRenderHandler unles

Error message

RenderHandler cannot be null. Use DefaultRenderHandler unless implementing your own

What it means

Thrown as NullReferenceException by ScreenshotOrNull when RenderHandler is null. The offscreen browser relies on a render handler to provide the bitmap buffer; without one there is no pixel data to capture. The message directs users to DefaultRenderHandler.

Source

Thrown at CefSharp.OffScreen/ChromiumWebBrowser.cs:482

            }
        }

        /// <summary>
        /// Immediately returns a copy of the last rendering from Chrome,
        /// or null if no rendering has occurred yet.
        /// Chrome also renders the page loading, so if you want to see a complete rendering,
        /// 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)
                {

View on GitHub (pinned to 16bc6e0711)

Solutions

Ensure RenderHandler is set to a DefaultRenderHandler (or your custom IRenderHandler) before screenshotting.
Check RenderHandler != null before calling ScreenshotOrNull.
Use the ChromiumWebBrowser constructor overload or property setter that assigns the render handler.

Example fix

// before
var bmp = browser.ScreenshotOrNull();

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

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

public static bool HasRenderHandler(ChromiumWebBrowser b) => b.RenderHandler != null;

Try / catch

try { return browser.ScreenshotOrNull(); }
catch (NullReferenceException ex) when (ex.Message.Contains("RenderHandler")) { /* assign handler */ }

Prevention

Assign RenderHandler immediately after constructing ChromiumWebBrowser.
Use DefaultRenderHandler unless you implement custom rendering.
Check RenderHandler != null before screenshot calls.

When it happens

Trigger: Calling ScreenshotOrNull before assigning ChromiumWebBrowser.RenderHandler, or after explicitly setting it to null. Constructing ChromiumWebBrowser with a custom render handler configuration that failed to assign.

Common situations: Creating a ChromiumWebBrowser and immediately calling ScreenshotOrNull before the render handler is wired. Clearing RenderHandler during teardown and then screenshotting.

Related errors

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