iOfficeAI/OfficeCLI · error · CliException

range_target_not_found

range_target_not_found

Error message

--range target '{clipArg}' matched no rendered element.

What it means

The --range clip path renders the full HTML preview then calls HtmlScreenshot.CaptureClipped with ResolveClipDataPaths(clipArg). When the headless browser loaded the page but the clip selector matched zero elements, CaptureClipped returns Ok=false with Error="clip_target_not_found", and this CliException surfaces it. It means the data-path syntax was valid but pointed at nothing the preview actually emitted (e.g. a shape index that does not exist, a cell range outside the used area).

Source

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

                var pngPath = outArg ?? Path.Combine(Path.GetTempPath(), $"officecli_screenshot_{Path.GetFileNameWithoutExtension(file.Name)}_{DateTime.Now:HHmmss}_{Guid.NewGuid():N}.png");
                if (directPng != null)
                {
                    File.WriteAllBytes(pngPath, directPng);
                }
                else
                {
                    // SECURITY: random token in temp filename — same rationale as the html/--browser path.
                    var tmpHtml = Path.Combine(Path.GetTempPath(), $"officecli_preview_{Path.GetFileNameWithoutExtension(file.Name)}_{DateTime.Now:HHmmss}_{Guid.NewGuid():N}.html");
                    File.WriteAllText(tmpHtml, html!);
                    var r = clipArg != null
                        ? OfficeCli.Core.HtmlScreenshot.CaptureClipped(tmpHtml, pngPath,
                            OfficeCli.Core.HtmlScreenshot.ResolveClipDataPaths(clipArg))
                        : OfficeCli.Core.HtmlScreenshot.Capture(tmpHtml, pngPath, screenshotWidth, screenshotHeight);
                    try { File.Delete(tmpHtml); } catch { /* ignore */ }
                    if (!r.Ok && r.Error == "clip_target_not_found")
                    {
                        throw new OfficeCli.Core.CliException(
                            $"--range target '{clipArg}' matched no rendered element.")
                        {
                            Code = "range_target_not_found",
                            Suggestion = "Use a data-path the HTML preview emits (xlsx: 'Sheet1!A1:C3' within the sheet's used area; pptx: '/slide[N]/shape[K]'; docx: '/body/table[N]' or '/body/p[N]'). `query` lists element paths.",
                        };
                    }
                    if (!r.Ok)
                    {
                        throw new OfficeCli.Core.CliException(
                            "No headless browser available. Install Chrome/Edge/Chromium or Firefox, or `pip install playwright && playwright install chromium`."
                            + (r.Error != null ? $" Last error: {r.Error}" : ""))
                        { Code = "no_screenshot_backend" };
                    }
                }
                Console.WriteLine(Path.GetFullPath(pngPath));
                if (handler is OfficeCli.Handlers.PowerPointHandler pptCount)
                    Console.Error.WriteLine($"[pages] total={pptCount.GetSlideCount()}");
                if (browser)

View on GitHub (pinned to 1ced45e900)

Solutions

1. Run `query` on the file to list the element paths the preview actually emits, then copy an exact path
2. Confirm the index is within bounds (slide count, table count, used cell range)
3. Use the correct grammar for the format (xlsx: Sheet1!A1:C3; pptx: /slide[N]/shape[K]; docx: /body/table[N] or /body/p[N])
4. Drop --range to capture the whole preview and verify the element exists

Example fix

// before
officecli view --mode screenshot --range '/slide[9]/shape[4]' deck.pptx
// after (discover valid paths first)
officecli query deck.pptx   // then use a path it lists, e.g.:
officecli view --mode screenshot --range '/slide[2]/shape[1]' deck.pptx

// Discover valid element paths before clipping.
// 1) Run `query` on the file to list emitted data-paths.
// 2) Verify the intended --range path appears in that list.
var knownPaths = QueryElements(file); // your call to the `query` surface
string range = "/slide[2]/shape[1]";
if (!knownPaths.Contains(range))
{
    // pick a path from knownPaths instead of risking range_target_not_found
}

try
{
    // invoke view --mode screenshot --range path file
}
catch (OfficeCli.Core.CliException ex) when (ex.Code == "range_target_not_found")
{
    // re-query the file for valid paths and retry with one of them
}

When it happens

Trigger: `view --mode screenshot --range '/slide[9]/shape[4]' deck.pptx` where the deck has fewer than 9 slides or slide 9 has no shape 4; `--range 'Sheet1!Z100' book.xlsx` beyond the used range; `--range '/body/table[3]' doc.docx` with fewer than 3 tables. The selector parsed fine but matched no DOM node.

Common situations: Off-by-one shape/table indices; referencing a sheet/cell outside the used area; stale data-path copied from a different document version; wrong path grammar for the format (pptx uses /slide[N]/shape[K], docx uses /body/table[N] or /body/p[N]).

Related errors

• Invalid --page value '{pageFilter}': expected N or M-N or co
• Invalid range '{spec}': offsets must be non-negative.
• no_screenshot_backend
• Invalid color transform '{token}': raw value {raw} out of ra
• Invalid color transform '{token}': percentage {raw} out of r

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