{"record":{"id":"3948ed129a59952e","repo":"iOfficeAI/OfficeCLI","slug":"invalid-value-3948ed","errorCode":"invalid_value","errorMessage":"--range on view text is only supported for xlsx (cell ranges like 'Sheet1!A1:C10'). For {format}, use --start/--end to bound the output.","messagePattern":"--range on view text is only supported for xlsx \\(cell ranges like 'Sheet1!A1:C10'\\)\\. For (.+?), use --start/--end to bound the output\\.","errorType":"exception","errorClass":"CliException","httpStatus":null,"severity":"error","filePath":"src/officecli/Core/IDocumentHandler.cs","lineNumber":52,"sourceCode":"        if (Before != null)\n        {\n            return anchorFinder(Before);\n        }\n        return null; // append\n    }\n}\n\n/// <summary>\n/// Shared guard for handlers that do not support the `view text --range`\n/// cell-range subset (docx/pptx/plugins). Kept next to the interface so the\n/// error text stays identical across handlers.\n/// </summary>\npublic static class ViewRangeGuard\n{\n    public static void RejectTextRange(string? range, string format)\n    {\n        if (range == null) return;\n        throw new CliException(\n            $\"--range on view text is only supported for xlsx (cell ranges like 'Sheet1!A1:C10'). For {format}, use --start/--end to bound the output.\")\n        { Code = \"invalid_value\" };\n    }\n}\n\n/// <summary>\n/// Common interface for all document types (Word/Excel/PowerPoint).\n/// Each handler implements the three-layer architecture:\n///   - Semantic layer: view (text/annotated/outline/stats/issues)\n///   - Query layer: get, query, set\n///   - Raw layer: raw XML access\n/// </summary>\npublic interface IDocumentHandler : IDisposable\n{\n    // === Semantic Layer ===\n    // range: xlsx-only cell-range subset ('Sheet1!A1:C10' or '/Sheet1/A1:C10');\n    // docx/pptx throw invalid_value when non-null (use --start/--end there).\n    string ViewAsText(int? startLine = null, int? endLine = null, int? maxLines = null, HashSet<string>? cols = null, string? range = null);","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Core/IDocumentHandler.cs#L34-L70","documentation":"Thrown by ViewRangeGuard.RejectTextRange when the --range argument is passed to 'view text' on a non-xlsx document handler (docx, pptx, or plugins). The --range flag is an xlsx-only cell-range subset selector (e.g. 'Sheet1!A1:C10'); Word, PowerPoint, and plugin handlers do not have a cell-range model, so the guard rejects it immediately with code 'invalid_value'. The error message points the user to --start/--end, which bound the text output by line range and work on all formats.","triggerScenarios":"Running 'view text --range Sheet1!A1:C10' on a .docx or .pptx file. Calling handler.ViewAsText(range: \"somevalue\") from a docx/pptx/plugin handler. The guard is a static no-op when range is null, so it only fires when a non-null range string is passed to a handler whose ViewAsText implementation calls ViewRangeGuard.RejectTextRange(range, format).","commonSituations":"An agent script or batch file that applies the same --range argument across multiple document types without checking the format first. A user accustomed to xlsx cell-range syntax trying the same flag on a Word document. A dump→replay pipeline that captured a --range from an xlsx and blindly replays it on a docx.","solutions":["Replace --range with --start/--end to bound the text output by line number (works on all formats).","If targeting xlsx specifically, ensure the command is actually operating on an .xlsx file and not a .docx/.pptx.","Remove the --range argument entirely to get the full text output.","For format-aware batch scripts, branch on the file extension before deciding whether to use --range (xlsx) or --start/--end (other formats)."],"exampleFix":"// before — rejected on docx/pptx\nview text --range 'Sheet1!A1:C10' doc.docx\n\n// after — use --start/--end for line bounding\nview text --start 10 --end 20 doc.docx","handlingStrategy":"validation","validationCode":"// Check the document format before passing --range\nstring extension = Path.GetExtension(filePath).ToLowerInvariant();\nif (extension != \".xlsx\" && requestedRange != null)\n{\n    // Don't pass range to non-xlsx; use start/end instead\n    handler.ViewAsText(startLine: start, endLine: end, range: null);\n}\nelse\n{\n    handler.ViewAsText(startLine: start, endLine: end, range: requestedRange);\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    handler.ViewAsText(range: range);\n}\ncatch (CliException ex) when (ex.Code == \"invalid_value\" && ex.Message.Contains(\"--range\"))\n{\n    // Fallback: retry without range, using start/end\n    handler.ViewAsText(startLine: start, endLine: end, range: null);\n}","preventionTips":["Gate --range behind a format check: only pass it when the file extension is .xlsx.","In multi-format batch scripts, branch on extension to choose --range (xlsx) vs --start/--end (docx/pptx).","Treat --range as xlsx-exclusive in documentation and code comments so future contributors don't generalize it."],"tags":["cli","view-text","range","format-specific","argument-validation"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}