iOfficeAI/OfficeCLI · error · CliException

no_screenshot_backend

no_screenshot_backend

Error message

No headless browser available. Install Chrome/Edge/Chromium or Firefox, or `pip install playwright && playwright install chromium`. Last error: {r.Error}

What it means

The HTML-fallback rasterizer needs a headless browser. When HtmlScreenshot.Capture/CaptureClipped returns Ok=false with an error other than clip_target_not_found, it means the browser discovery/launch itself failed — no Chrome/Edge/Chromium/Firefox binary found and Playwright not installed, or the browser crashed. The Last error detail is appended so the underlying failure (binary not found, sandbox error, etc.) is visible.

Source

Thrown at src/officecli/CommandBuilder.View.cs:472

                    var tmpHtml = Path.Combine(Path.GetTempPath(), $"officecli_preview_{Path.GetFileNameWithoutExtension(file.Name)}_{DateTime.Now:HHmmss}_{Guid.NewGuid():N}.html");
                    File.WriteAllText(tmpHtml, html!);
                    var r = clipArg != null
                        ? OfficeCli.Core.HtmlScreenshot.CaptureClipped(tmpHtml, pngPath,
                            OfficeCli.Core.HtmlScreenshot.ResolveClipDataPaths(clipArg))
                        : OfficeCli.Core.HtmlScreenshot.Capture(tmpHtml, pngPath, screenshotWidth, screenshotHeight);
                    try { File.Delete(tmpHtml); } catch { /* ignore */ }
                    if (!r.Ok && r.Error == "clip_target_not_found")
                    {
                        throw new OfficeCli.Core.CliException(
                            $"--range target '{clipArg}' matched no rendered element.")
                        {
                            Code = "range_target_not_found",
                            Suggestion = "Use a data-path the HTML preview emits (xlsx: 'Sheet1!A1:C3' within the sheet's used area; pptx: '/slide[N]/shape[K]'; docx: '/body/table[N]' or '/body/p[N]'). `query` lists element paths.",
                        };
                    }
                    if (!r.Ok)
                    {
                        throw new OfficeCli.Core.CliException(
                            "No headless browser available. Install Chrome/Edge/Chromium or Firefox, or `pip install playwright && playwright install chromium`."
                            + (r.Error != null ? $" Last error: {r.Error}" : ""))
                        { Code = "no_screenshot_backend" };
                    }
                }
                Console.WriteLine(Path.GetFullPath(pngPath));
                if (handler is OfficeCli.Handlers.PowerPointHandler pptCount)
                    Console.Error.WriteLine($"[pages] total={pptCount.GetSlideCount()}");
                if (browser)
                {
                    try
                    {
                        var psi = new System.Diagnostics.ProcessStartInfo(pngPath) { UseShellExecute = true };
                        System.Diagnostics.Process.Start(psi);
                    }
                    catch { /* silently ignore if image viewer can't be opened */ }
                }
                return 0;

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Install a headless browser: Chrome, Edge, Chromium, or Firefox on the PATH
  2. Or `pip install playwright && playwright install chromium`
  3. On Linux, install browser runtime libs (libnss3, libatk1.0, libxkbcommon0, libgbm1, etc.) or use Playwright which bundles deps
  4. Read the appended `Last error:` to pinpoint the exact launch failure and address it

Example fix

// before: no browser installed, screenshot fails
// after
pip install playwright && playwright install chromium
officecli view --mode screenshot deck.pptx
Defensive patterns

Strategy: fallback

Validate before calling

// Ensure a headless browser exists before any HTML-path screenshot.
bool HasBrowser() =>
    OfficeCli.Core.HtmlScreenshot.ProbeBrowsers().Any(); // or check common binaries
if (!HasBrowser())
{
    // install a browser or playwright; otherwise native-only formats will fail
}

Try / catch

try
{
    // invoke view --mode screenshot file (HTML fallback path)
}
catch (OfficeCli.Core.CliException ex) when (ex.Code == "no_screenshot_backend")
{
    // install a browser: Chrome/Edge/Chromium/Firefox, or
    // `pip install playwright && playwright install chromium`, then retry
    Console.Error.WriteLine(ex.Message);
}

Prevention

When it happens

Trigger: Any screenshot/preview that falls through to the HTML path (native unavailable, --render html, or html-only format) on a machine with zero installed browsers and no Playwright runtime; or a browser binary present but failing to launch (missing libs, sandbox/permissions, headless flag unsupported in an old version).

Common situations: Minimal Linux server/container with no browser; PATH missing the browser; Chrome present but libnss/libatk absent; Playwright installed but `playwright install chromium` not run; snap-confined environment blocking browser launch.

Related errors

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/7899e26a26863d72. Report an issue: GitHub.