{"record":{"id":"ca6e983c158c018a","repo":"iOfficeAI/OfficeCLI","slug":"native-unavailable","errorCode":"native_unavailable","errorMessage":"--render native requires Windows with Microsoft PowerPoint installed.","messagePattern":"--render native requires Windows with Microsoft PowerPoint installed\\.","errorType":"exception","errorClass":"CliException","httpStatus":null,"severity":"error","filePath":"src/officecli/CommandBuilder.View.cs","lineNumber":282,"sourceCode":"                    {\n                        try\n                        {\n                            if (gridColsResolved > 0)\n                            {\n                                const int gap = 12, pad = 12;\n                                int cellW = Math.Max(1, (int)Math.Round((screenshotWidth - 2 * pad - (gridColsResolved - 1) * gap) / (double)gridColsResolved));\n                                int cellH = Math.Max(1, (int)Math.Round(cellW * (double)nativeH / nativeW));\n                                directPng = OfficeCli.Core.PowerPointPngBackend.RenderGrid(file.FullName, pStart ?? 1, pEnd ?? pptHandler.GetSlideCount(), cellW, cellH, gridColsResolved, gap, pad);\n                            }\n                            else\n                            {\n                                directPng = OfficeCli.Core.PowerPointPngBackend.Render(file.FullName, pStart ?? 1, pEnd ?? pStart ?? 1, exportW, exportH);\n                            }\n                        }\n                        catch { directPng = null; }\n                    }\n                    if (renderMode == \"native\" && directPng == null)\n                        throw new OfficeCli.Core.CliException(\"--render native requires Windows with Microsoft PowerPoint installed.\")\n                        { Code = \"native_unavailable\", Suggestion = \"Use --render html or --render auto.\" };\n\n                    if (directPng == null)\n                    {\n                        html = RenderViaRegistry(pptHandler, \"pptx\", new OfficeCli.Core.Rendering.RenderOptions\n                        { StartPage = pStart, EndPage = pEnd, GridColumns = gridColsResolved, ViewportPx = screenshotWidth })!;\n\n                        // The generic 4:3 viewport (1600×1200) letterboxes a single slide with\n                        // canvas padding. When capturing one slide (not a multi-slide range or\n                        // grid), size the viewport to the slide so the PNG is the slide,\n                        // padding-free (ViewAsHtml scales the slide to fill + zeroes the headless\n                        // page padding). Default dims -> the slide's 96-DPI native pixels;\n                        // a custom --screenshot-width -> that width with an aspect-matched height.\n                        // Multi-slide ranges stack vertically and keep the tall viewport.\n                        if (pStart == pEnd && gridCols == 0)\n                        {\n                            if (screenshotWidth == 1600 && screenshotHeight == 1200)\n                                (screenshotWidth, screenshotHeight) = (nativeW, nativeH);","sourceCodeStart":264,"sourceCodeEnd":300,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/CommandBuilder.View.cs#L264-L300","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nofficecli view --mode screenshot --render native deck.pptx\n// after\nofficecli view --mode screenshot --render auto deck.pptx","handlingStrategy":"fallback","validationCode":"// Before requesting native pptx rendering, confirm Windows + PowerPoint capability.\nbool nativePptxCapable = OperatingSystem.IsWindows();\nstring renderMode = nativePptxCapable ? \"native\" : \"auto\"; // or \"html\"\n// pass renderMode to the view invocation; --render auto falls back silently","typeGuard":null,"tryCatchPattern":"try\n{\n    // invoke view --mode screenshot --render native deck.pptx\n}\ncatch (OfficeCli.Core.CliException ex) when (ex.Code == \"native_unavailable\")\n{\n    // Environment lacks PowerPoint; retry with --render html or --render auto\n    // invoke view --mode screenshot --render auto deck.pptx\n}","preventionTips":["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"],"tags":["render","native","windows","powerpoint","environment","com"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}