iOfficeAI/OfficeCLI · error · CliException

refresh_failed

refresh_failed

Error message

refresh failed (Word backend unavailable and HTML fallback failed — no headless browser found).

What it means

Refresh tries two backends in order: the OS-native Word backend (Windows + Word only), then an HTML fallback via a headless browser. This fires when both failed — typically non-Windows without Word AND no headless browser available for the HTML path.

Source

Thrown at src/officecli/CommandBuilder.Refresh.cs:47

            var ext = Path.GetExtension(file.FullName).ToLowerInvariant();
            if (ext != ".docx" && ext != ".docm")
                throw new CliException($"refresh currently only supports .docx files (got {ext}).")
                { Code = "unsupported_type" };

            bool ok = false;
            string backend = "";
            if (OperatingSystem.IsWindows())
            {
                ok = WordPdfBackend.RefreshFields(file.FullName);
                if (ok) backend = "word";
            }
            if (!ok)
            {
                ok = WordHtmlRefresh.RefreshViaHtml(file.FullName);
                if (ok) backend = "html";
            }
            if (!ok)
                throw new CliException("refresh failed (Word backend unavailable and HTML fallback failed — no headless browser found).")
                { Code = "refresh_failed" };

            var msg = $"Refreshed: {file.FullName} (backend: {backend})";
            if (backend == "html")
                Console.Error.WriteLine("Note: HTML fallback used. TOC page numbers reflect officecli's HTML pagination, which may differ from Word's layout.");
            if (json) Console.WriteLine(OutputFormatter.WrapEnvelopeText(msg));
            else Console.WriteLine(msg);
            return 0;
        }, json); });

        return cmd;
    }
}

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Install a headless browser (Chrome or Edge) for the HTML fallback.
  2. Run on Windows with Word installed for the native backend.
  3. If neither is available, skip refresh and accept that TOC page numbers may be stale.

Example fix

# before (Linux, no browser): officecli refresh doc.docx  -> refresh_failed
# install a headless browser, then:
officecli refresh doc.docx   # uses html backend
Defensive patterns

Strategy: validation

Validate before calling

bool canRefresh = (OperatingSystem.IsWindows() && WordPdfBackend.IsAvailable())
    || HeadlessBrowserDetector.IsInstalled();
if (!canRefresh)
    Console.Error.WriteLine("Skipping refresh: no Word or headless browser available.");

Try / catch

// Refresh is best-effort: catch and continue with stale fields if unavailable.
try { RunRefresh(doc); }
catch (CliException e) when (e.Code == "refresh_failed") {
    Console.Error.WriteLine($"Warning: could not refresh fields ({e.Message}); TOC may be stale.");
}

Prevention

When it happens

Trigger: Running 'officecli refresh doc.docx' on Linux/macOS without a headless browser installed; on Windows without Word installed and no browser fallback.

Common situations: CI on Linux with no Chrome/Edge headless; a minimal container; Word not installed on the dev box.

Related errors

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