iOfficeAI/OfficeCLI · error · CliException

invalid_value

invalid_value

Error message

--range on view text is only supported for xlsx (cell ranges like 'Sheet1!A1:C10'). For {format}, use --start/--end to bound the output.

What it means

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.

Source

Thrown at src/officecli/Core/IDocumentHandler.cs:52

        if (Before != null)
        {
            return anchorFinder(Before);
        }
        return null; // append
    }
}

/// <summary>
/// Shared guard for handlers that do not support the `view text --range`
/// cell-range subset (docx/pptx/plugins). Kept next to the interface so the
/// error text stays identical across handlers.
/// </summary>
public static class ViewRangeGuard
{
    public static void RejectTextRange(string? range, string format)
    {
        if (range == null) return;
        throw new CliException(
            $"--range on view text is only supported for xlsx (cell ranges like 'Sheet1!A1:C10'). For {format}, use --start/--end to bound the output.")
        { Code = "invalid_value" };
    }
}

/// <summary>
/// Common interface for all document types (Word/Excel/PowerPoint).
/// Each handler implements the three-layer architecture:
///   - Semantic layer: view (text/annotated/outline/stats/issues)
///   - Query layer: get, query, set
///   - Raw layer: raw XML access
/// </summary>
public interface IDocumentHandler : IDisposable
{
    // === Semantic Layer ===
    // range: xlsx-only cell-range subset ('Sheet1!A1:C10' or '/Sheet1/A1:C10');
    // docx/pptx throw invalid_value when non-null (use --start/--end there).
    string ViewAsText(int? startLine = null, int? endLine = null, int? maxLines = null, HashSet<string>? cols = null, string? range = null);

View on GitHub (pinned to 1ced45e900)

Solutions

1. Replace --range with --start/--end to bound the text output by line number (works on all formats).
2. If targeting xlsx specifically, ensure the command is actually operating on an .xlsx file and not a .docx/.pptx.
3. Remove the --range argument entirely to get the full text output.
4. For format-aware batch scripts, branch on the file extension before deciding whether to use --range (xlsx) or --start/--end (other formats).

Example fix

// before — rejected on docx/pptx
view text --range 'Sheet1!A1:C10' doc.docx

// after — use --start/--end for line bounding
view text --start 10 --end 20 doc.docx

// Check the document format before passing --range
string extension = Path.GetExtension(filePath).ToLowerInvariant();
if (extension != ".xlsx" && requestedRange != null)
{
    // Don't pass range to non-xlsx; use start/end instead
    handler.ViewAsText(startLine: start, endLine: end, range: null);
}
else
{
    handler.ViewAsText(startLine: start, endLine: end, range: requestedRange);
}

try
{
    handler.ViewAsText(range: range);
}
catch (CliException ex) when (ex.Code == "invalid_value" && ex.Message.Contains("--range"))
{
    // Fallback: retry without range, using start/end
    handler.ViewAsText(startLine: start, endLine: end, range: null);
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• invalid_argument
• missing_argument
• batch: --commands and --input are mutually exclusive. Pick o
• invalid_issue_type
• Invalid range '{spec}': offsets must be non-negative.

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