{"record":{"id":"d9255a908a35c026","repo":"iOfficeAI/OfficeCLI","slug":"refresh-failed","errorCode":"refresh_failed","errorMessage":"refresh failed (Word backend unavailable and HTML fallback failed — no headless browser found).","messagePattern":"refresh failed \\(Word backend unavailable and HTML fallback failed — no headless browser found\\)\\.","errorType":"exception","errorClass":"CliException","httpStatus":null,"severity":"error","filePath":"src/officecli/CommandBuilder.Refresh.cs","lineNumber":47,"sourceCode":"            var ext = Path.GetExtension(file.FullName).ToLowerInvariant();\n            if (ext != \".docx\" && ext != \".docm\")\n                throw new CliException($\"refresh currently only supports .docx files (got {ext}).\")\n                { Code = \"unsupported_type\" };\n\n            bool ok = false;\n            string backend = \"\";\n            if (OperatingSystem.IsWindows())\n            {\n                ok = WordPdfBackend.RefreshFields(file.FullName);\n                if (ok) backend = \"word\";\n            }\n            if (!ok)\n            {\n                ok = WordHtmlRefresh.RefreshViaHtml(file.FullName);\n                if (ok) backend = \"html\";\n            }\n            if (!ok)\n                throw new CliException(\"refresh failed (Word backend unavailable and HTML fallback failed — no headless browser found).\")\n                { Code = \"refresh_failed\" };\n\n            var msg = $\"Refreshed: {file.FullName} (backend: {backend})\";\n            if (backend == \"html\")\n                Console.Error.WriteLine(\"Note: HTML fallback used. TOC page numbers reflect officecli's HTML pagination, which may differ from Word's layout.\");\n            if (json) Console.WriteLine(OutputFormatter.WrapEnvelopeText(msg));\n            else Console.WriteLine(msg);\n            return 0;\n        }, json); });\n\n        return cmd;\n    }\n}\n","sourceCodeStart":29,"sourceCodeEnd":61,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/CommandBuilder.Refresh.cs#L29-L61","documentation":"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.","triggerScenarios":"Running 'officecli refresh doc.docx' on Linux/macOS without a headless browser installed; on Windows without Word installed and no browser fallback.","commonSituations":"CI on Linux with no Chrome/Edge headless; a minimal container; Word not installed on the dev box.","solutions":["Install a headless browser (Chrome or Edge) for the HTML fallback.","Run on Windows with Word installed for the native backend.","If neither is available, skip refresh and accept that TOC page numbers may be stale."],"exampleFix":"# before (Linux, no browser): officecli refresh doc.docx  -> refresh_failed\n# install a headless browser, then:\nofficecli refresh doc.docx   # uses html backend","handlingStrategy":"validation","validationCode":"bool canRefresh = (OperatingSystem.IsWindows() && WordPdfBackend.IsAvailable())\n    || HeadlessBrowserDetector.IsInstalled();\nif (!canRefresh)\n    Console.Error.WriteLine(\"Skipping refresh: no Word or headless browser available.\");","typeGuard":null,"tryCatchPattern":"// Refresh is best-effort: catch and continue with stale fields if unavailable.\ntry { RunRefresh(doc); }\ncatch (CliException e) when (e.Code == \"refresh_failed\") {\n    Console.Error.WriteLine($\"Warning: could not refresh fields ({e.Message}); TOC may be stale.\");\n}","preventionTips":["Provision a headless browser (Chrome/Edge) in non-Windows CI.","Gate refresh on backend availability; treat failure as non-fatal.","On Windows, ensure Word is installed for the native backend."],"tags":["refresh","backend","headless-browser","platform"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}