iOfficeAI/OfficeCLI · error · CliException

page_count_unavailable

page_count_unavailable

Error message

--page-count: failed to get page count (Word backend and HTML fallback both unavailable).

What it means

The --page-count (withPages) stat for Word tries two sources: first WordPdfBackend.GetPageCount on Windows COM (line 601), then an HTML DOM fallback that renders the doc to HTML and reads GetPageCountFromDom (lines 605-610). If both return null (non-Windows without a working HTML render, or the HTML DOM parse yielding no page count), the command cannot determine pages and throws page_count_unavailable.

Source

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

            int? withPagesValue = null;
            if (withPages && (mode.ToLowerInvariant() is "stats" or "s") && handler is OfficeCli.Handlers.WordHandler wordHandlerForCount)
            {
                if (OperatingSystem.IsWindows())
                {
                    try { withPagesValue = OfficeCli.Core.WordPdfBackend.GetPageCount(file.FullName); } catch { withPagesValue = null; }
                }
                if (withPagesValue == null)
                {
                    var tmpHtml = Path.Combine(Path.GetTempPath(), $"officecli_pc_{Path.GetFileNameWithoutExtension(file.Name)}_{Guid.NewGuid():N}.html");
                    try
                    {
                        File.WriteAllText(tmpHtml, RenderViaRegistry(wordHandlerForCount, "docx", new OfficeCli.Core.Rendering.RenderOptions())!);
                        withPagesValue = OfficeCli.Core.HtmlScreenshot.GetPageCountFromDom(tmpHtml);
                    }
                    finally { try { File.Delete(tmpHtml); } catch { } }
                }
                if (withPagesValue == null)
                    throw new OfficeCli.Core.CliException("--page-count: failed to get page count (Word backend and HTML fallback both unavailable).")
                    { Code = "page_count_unavailable" };
            }

            if (json)
            {
                // Structured JSON output — no Content string wrapping
                var modeKey = mode.ToLowerInvariant();
                if (modeKey is "stats" or "s")
                {
                    var statsJson = handler.ViewAsStatsJson();
                    if (withPagesValue.HasValue) statsJson["pages"] = withPagesValue.Value;
                    Console.WriteLine(OutputFormatter.WrapEnvelope(statsJson.ToJsonString(OutputFormatter.PublicJsonOptions)));
                }
                else if (modeKey is "outline" or "o")
                    Console.WriteLine(OutputFormatter.WrapEnvelope(handler.ViewAsOutlineJson().ToJsonString(OutputFormatter.PublicJsonOptions)));
                else if (modeKey is "text" or "t")
                    Console.WriteLine(OutputFormatter.WrapEnvelope(handler.ViewAsTextJson(start, end, maxLines, cols, clipArg).ToJsonString(OutputFormatter.PublicJsonOptions)));
                else if (modeKey is "annotated" or "a")

View on GitHub (pinned to 1ced45e900)

Solutions

1. Run on Windows with Word installed so WordPdfBackend.GetPageCount works
2. Drop --page-count and use --mode stats without it (page count is optional)
3. Ensure the docx HTML preview renders (check `view --mode html doc.docx` succeeds) and emits the PAGES marker
4. Install a headless browser / verify renderer registration so the HTML fallback path is healthy

Example fix

// before
officecli view --mode stats --page-count doc.docx   // fails on Linux
// after
officecli view --mode stats doc.docx   // omit --page-count

// Only request --page-count where it can be satisfied (Windows+Word or healthy HTML fallback).
bool pageCountLikely = OperatingSystem.IsWindows() || HtmlPathHealthy();
bool usePageCount = pageCountLikely;
// otherwise omit --page-count to avoid page_count_unavailable

try
{
    // invoke view --mode stats --page-count doc.docx
}
catch (OfficeCli.Core.CliException ex) when (ex.Code == "page_count_unavailable")
{
    // retry without --page-count (pages are optional in stats)
    // invoke view --mode stats doc.docx
}

When it happens

Trigger: `view --mode stats --page-count doc.docx` on a host where Word COM is unavailable AND the HTML/DOM page-count extraction fails (no headless browser needed for DOM count, but the HTML render itself can fail, or the DOM lacks the PAGES:N marker). Windows without Word + a doc whose HTML preview doesn't paginate; or the temp HTML write/render threw.

Common situations: Linux/macOS where Word COM never runs and the HTML fallback is the only hope; a doc whose HTML preview omits the <title>PAGES:N> pagination marker; RenderViaRegistry returning null HTML (no renderer); permission errors writing temp HTML.

Related errors

• no_screenshot_backend
• unsupported_type
• native_unavailable
• range_target_not_found
• Invalid --page value '{pageFilter}': expected N or M-N or co

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