What causes "viewPort.Scale must be greater than 0." in cefsharp/CefSharp?

Set viewPort.Scale to a positive value (typically 1.0 for 1:1 capture) before calling CaptureScreenshotAsync.

cefsharp/CefSharp · error · ArgumentException

viewPort.Scale must be greater than 0.

Error message

viewPort.Scale must be greater than 0.

What it means

CaptureScreenshotAsync validates the optional Viewport parameter: its Scale must be strictly greater than zero because CEF uses it to compute the capture rectangle. A zero or negative scale produces an invalid capture region, so the call is rejected before reaching the DevTools client.

Source

Thrown at CefSharp.Wpf/HwndHost/ChromiumWebBrowser.cs:1920

        }

        /// <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>
        /// Throw exception if browser not initialized.
        /// </summary>
        /// <exception cref="Exception">Thrown when an exception error condition occurs.</exception>
        private void ThrowExceptionIfBrowserNotInitialized()
        {
            if (!InternalIsBrowserInitialized())
            {

View on GitHub (pinned to 16bc6e0711)

Solutions

Set viewPort.Scale to a positive value (typically 1.0 for 1:1 capture) before calling CaptureScreenshotAsync.
Pass null for viewPort to capture the full viewport at default scale.
Validate viewPort?.Scale > 0 before the call.

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

if (viewPort != null && viewPort.Scale <= 0)
{
    throw new ArgumentException(
        $"viewPort.Scale must be > 0, got {viewPort.Scale}",
        nameof(viewPort));
}
// or simply default it
if (viewPort != null && viewPort.Scale <= 0)
    viewPort.Scale = 1.0;

await browser.CaptureScreenshotAsync(format, quality, viewPort);

Try / catch

try
{
    await browser.CaptureScreenshotAsync(format, quality, viewPort);
}
catch (ArgumentException ex) when (ex.Message.Contains("viewPort.Scale"))
{
    // retry with default scale
    viewPort.Scale = 1.0;
    await browser.CaptureScreenshotAsync(format, quality, viewPort);
}

Prevention

Always set Viewport.Scale to 1.0 unless a specific DPI-scaled capture is needed.
Pass null for viewPort when capturing the full viewport at default scale.
Validate computed scale values before passing.

When it happens

Trigger: Passing a Viewport whose Scale property is 0 or negative. The default-constructed Viewport may have Scale = 0 depending on how it was created.

Common situations: Computing Scale from a DPI ratio or zoom factor that evaluates to 0 (e.g. dividing by a zero screen dimension). Reusing a Viewport object that was partially initialized.

Related errors

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