cefsharp/CefSharp · error · ArgumentException

{nameof(viewPort)}.{nameof(viewPort.Scale)} must be greater

Error message

{nameof(viewPort)}.{nameof(viewPort.Scale)} must be greater than 0.

What it means

Thrown by ChromiumWebBrowser.CaptureScreenshotAsync when a Viewport argument is supplied whose Scale is zero or negative. Scale is a device-pixel multiplier applied to the capture region; a non-positive value produces an undefined/empty image, so CefSharp validates it up front before invoking the DevTools capture call.

Source

Thrown at CefSharp.WinForms/ChromiumWebBrowser.cs:509

        }

        /// <summary>
        /// Capture page screenshot.
        /// </summary>
        /// <param name="format">Image compression format (defaults to png).</param>
        /// <param name="quality">Compression quality from range [0..100] (jpeg only).</param>
        /// <param name="viewPort">Capture the screenshot of a given region only.</param>
        /// <param name="fromSurface">Capture the screenshot from the surface, rather than the view. Defaults to true.</param>
        /// <param name="captureBeyondViewport">Capture the screenshot beyond the viewport. Defaults to false.</param>
        /// <returns>A task that can be awaited to obtain the screenshot as a byte[].</returns>
        public async Task<byte[]> CaptureScreenshotAsync(CaptureScreenshotFormat format = CaptureScreenshotFormat.Png, int? quality = null, Viewport viewPort = null, bool fromSurface = true, bool captureBeyondViewport = false)
        {
            ThrowExceptionIfDisposed();
            ThrowExceptionIfBrowserNotInitialized();

            if(viewPort != null && viewPort.Scale <= 0)
            {
                throw new ArgumentException($"{nameof(viewPort)}.{nameof(viewPort.Scale)} must be greater than 0.");
            }

            using (var devToolsClient = browser.GetDevToolsClient())
            {
                var screenShot = await devToolsClient.Page.CaptureScreenshotAsync(format, quality, viewPort, fromSurface, captureBeyondViewport).ConfigureAwait(continueOnCapturedContext: false);

                return screenShot.Data;
            }
        }

        /// <summary>
        /// The javascript object repository, one repository per ChromiumWebBrowser instance.
        /// </summary>
        [Browsable(false), DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden)]
        public IJavascriptObjectRepository JavascriptObjectRepository
        {
            get
            {

View on GitHub (pinned to 16bc6e0711)

Solutions

1. Set Viewport.Scale to a positive value (1.0 for logical pixels, or the device pixel ratio) before calling CaptureScreenshotAsync.
2. Pass viewPort: null when you want a full-viewport capture at default scale.
3. Validate `viewPort == null || viewPort.Scale > 0` before invoking the method.
4. If computing scale dynamically, clamp it to a minimum of a small positive epsilon.

Example fix

// before
var vp = new Viewport { X = 0, Y = 0, Width = 800, Height = 600, Scale = 0 };
var bytes = await browser.CaptureScreenshotAsync(viewPort: vp); // throws

// after
var vp = new Viewport { X = 0, Y = 0, Width = 800, Height = 600, Scale = 1.0 };
var bytes = await browser.CaptureScreenshotAsync(viewPort: vp);

if (viewPort == null || viewPort.Scale > 0)
{
    var bytes = await browser.CaptureScreenshotAsync(viewPort: viewPort);
}

static bool IsValidViewport(Viewport vp) => vp == null || vp.Scale > 0;

When it happens

Trigger: Passing a Viewport with Scale <= 0; defaulting a Scale field to 0 and forgetting to set it; computing Scale from a DPI or zoom ratio that evaluated to zero.

Common situations: DPI-aware code computing scale = 0 when DPI is unset; reusing a Viewport struct whose Scale was never initialized; dividing by an unpopulated denominator.

Related errors

• {prop.Name} is required
• Screenshot already in progress, you must wait for the previo
• Browser has not yet finished initializing or is being dispos
• Unable to take screenshot while browser is loading
• IBrowserHost is null

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