iOfficeAI/OfficeCLI · error · CliException

native_unavailable

native_unavailable

Error message

--render native requires Windows with Microsoft PowerPoint installed.

What it means

Thrown when --render native is requested for a PowerPoint screenshot but the native COM backend produced no PNG. The native path only runs on Windows with PowerPoint installed, and the attempt is wrapped in a silent try/catch (directPng=null on any failure); an explicit --render native then converts that null into a hard error instead of falling back to HTML. So the cause is always an environment/dependency gap or a PowerPoint automation failure, never the file itself.

Source

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

                    {
                        try
                        {
                            if (gridColsResolved > 0)
                            {
                                const int gap = 12, pad = 12;
                                int cellW = Math.Max(1, (int)Math.Round((screenshotWidth - 2 * pad - (gridColsResolved - 1) * gap) / (double)gridColsResolved));
                                int cellH = Math.Max(1, (int)Math.Round(cellW * (double)nativeH / nativeW));
                                directPng = OfficeCli.Core.PowerPointPngBackend.RenderGrid(file.FullName, pStart ?? 1, pEnd ?? pptHandler.GetSlideCount(), cellW, cellH, gridColsResolved, gap, pad);
                            }
                            else
                            {
                                directPng = OfficeCli.Core.PowerPointPngBackend.Render(file.FullName, pStart ?? 1, pEnd ?? pStart ?? 1, exportW, exportH);
                            }
                        }
                        catch { directPng = null; }
                    }
                    if (renderMode == "native" && directPng == null)
                        throw new OfficeCli.Core.CliException("--render native requires Windows with Microsoft PowerPoint installed.")
                        { Code = "native_unavailable", Suggestion = "Use --render html or --render auto." };

                    if (directPng == null)
                    {
                        html = RenderViaRegistry(pptHandler, "pptx", new OfficeCli.Core.Rendering.RenderOptions
                        { StartPage = pStart, EndPage = pEnd, GridColumns = gridColsResolved, ViewportPx = screenshotWidth })!;

                        // The generic 4:3 viewport (1600×1200) letterboxes a single slide with
                        // canvas padding. When capturing one slide (not a multi-slide range or
                        // grid), size the viewport to the slide so the PNG is the slide,
                        // padding-free (ViewAsHtml scales the slide to fill + zeroes the headless
                        // page padding). Default dims -> the slide's 96-DPI native pixels;
                        // a custom --screenshot-width -> that width with an aspect-matched height.
                        // Multi-slide ranges stack vertically and keep the tall viewport.
                        if (pStart == pEnd && gridCols == 0)
                        {
                            if (screenshotWidth == 1600 && screenshotHeight == 1200)
                                (screenshotWidth, screenshotHeight) = (nativeW, nativeH);

View on GitHub (pinned to 1ced45e900)

Solutions

Pass --render html or --render auto to use the headless-browser HTML fallback path
Run on a Windows host with Microsoft PowerPoint installed and activated
Ensure PowerPoint COM automation is permitted and no other process holds the PowerPoint instance
On CI/Non-Windows, install a headless browser (Chrome/Edge/Chromium/Firefox or `pip install playwright && playwright install chromium`) so the HTML fallback can rasterize

Example fix

// before
officecli view --mode screenshot --render native deck.pptx
// after
officecli view --mode screenshot --render auto deck.pptx

Defensive patterns

Strategy: fallback

Validate before calling

// Before requesting native pptx rendering, confirm Windows + PowerPoint capability.
bool nativePptxCapable = OperatingSystem.IsWindows();
string renderMode = nativePptxCapable ? "native" : "auto"; // or "html"
// pass renderMode to the view invocation; --render auto falls back silently

Try / catch

try
{
    // invoke view --mode screenshot --render native deck.pptx
}
catch (OfficeCli.Core.CliException ex) when (ex.Code == "native_unavailable")
{
    // Environment lacks PowerPoint; retry with --render html or --render auto
    // invoke view --mode screenshot --render auto deck.pptx
}

Prevention

Default scripts to --render auto so a missing PowerPoint degrades to HTML instead of erroring
On CI, detect non-Windows and force --render html, plus install a headless browser
Only use --render native on a known Windows+PowerPoint host
Treat native as an optimization, not a requirement

When it happens

Trigger: Running `view --mode screenshot --render native deck.pptx` on macOS/Linux (the `OperatingSystem.IsWindows()` guard at line 263 skips the render, leaving directPng null), or on Windows where PowerPointPngBackend.Render/RenderGrid throws (PowerPoint missing, COM blocked, or automation error). Fires only when renderMode=="native"; --render auto silently falls back.

Common situations: CI on Linux containers without Office; macOS dev machines; Windows Server cores without an Office license; PowerPoint COM disabled by group policy; PowerPoint held open by another process causing COM failure.

Related errors

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