iOfficeAI/OfficeCLI · error · ArgumentException

Sheet not found: {shpSheetName}

Error message

Sheet not found: {shpSheetName}

What it means

Thrown by AddShape when the first segment of the parent path (the sheet name) does not match any worksheet in the workbook. FindWorksheet does a case-insensitive lookup against GetWorksheets() and returns null, which the null-coalescing ?? operator converts into this ArgumentException. It is a pure input-validation failure: no file mutation happens before the throw. The same guard exists on the sparkline path (error 545) and most other drawing add handlers.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Add.Drawings.cs:576

        // DEFERRED(xlsx/picture-anchor-mode) P12: enumerate all anchor
        // kinds (twoCell / oneCell / absolute) when counting picture slots.
        var picAnchors = picDrawingsPart.WorksheetDrawing
            .Elements<OpenXmlElement>()
            .Where(a => (a is XDR.TwoCellAnchor || a is XDR.OneCellAnchor || a is XDR.AbsoluteAnchor)
                && a.Descendants<XDR.Picture>().Any())
            .ToList();
        var picIdx = PathIndex.FromArrayIndex(picAnchors.IndexOf(anchor));

        return $"/{picSheetName}/picture[{picIdx}]";
    }

    private string AddShape(string parentPath, string type, InsertPosition? position, Dictionary<string, string> properties)
    {
        var index = position?.Index;
        var shpSegments = parentPath.TrimStart('/').Split('/', 2);
        var shpSheetName = shpSegments[0];
        var shpWorksheet = FindWorksheet(shpSheetName)
            ?? throw new ArgumentException($"Sheet not found: {shpSheetName}");

        // CONSISTENCY(ole-width-units): accept `anchor=B2:F7` as a cell
        // range (same grammar as OLE's anchor=), alongside the legacy
        // x/y/width/height (column/row units) form. When both are
        // supplied, warn and let anchor= win — it defines the full
        // rectangle, so width/height are ambiguous.
        // CONSISTENCY(ref-alias): `ref=<cell>` maps to single-cell
        // anchor `<cell>:<cell>`, matching cell/comment/table which
        // accept `ref=` as the placement address. Explicit `anchor=`
        // wins if both are given.
        if (!properties.ContainsKey("anchor")
            && properties.TryGetValue("ref", out var shpRefProp)
            && !string.IsNullOrWhiteSpace(shpRefProp))
        {
            var refTrim = shpRefProp.Trim();
            if (!refTrim.Contains(':'))
            {
                // Single-cell ref (e.g. "B2"): expand to a 1x1 cell

View on GitHub (pinned to 1ced45e900)

Solutions

1. List the actual sheets with the tool's sheet-listing command and copy the exact name (FindWorksheet is case-insensitive, but trailing spaces and exact spelling matter).
2. Correct the leading path segment to match an existing sheet, e.g. `/Sheet1` instead of `/SheetX`.
3. If scripting, resolve the sheet name dynamically from the workbook before building the path instead of hard-coding it.

Example fix

// before
add ./book.xlsx /SalesData shape --type rectangle --anchor B2:F7
// after
add ./book.xlsx /Sheet1 shape --type rectangle --anchor B2:F7

// Resolve the sheet against the workbook before building the path.
// FindWorksheet is case-insensitive; mirror that here.
var sheets = GetWorksheetNames(workbook); // your enumeration
if (!sheets.Any(s => s.Equals(sheetName, StringComparison.OrdinalIgnoreCase)))
    throw new InvalidOperationException(
        $"Sheet '{sheetName}' not found. Available: {string.Join(", ", sheets)}");

static bool SheetExists(WorkbookPart wbp, string sheetName)
    => wbp.Workbook.Sheets.Elements<Sheet>()
        .Any(s => s.Name.Value.Equals(sheetName, StringComparison.OrdinalIgnoreCase));

try { handler.Add(...); }
catch (ArgumentException ex) when (ex.Message.StartsWith("Sheet not found"))
{
    // re-resolve sheet list, surface to user, do not retry blindly
    Console.Error.WriteLine(ex.Message);
}

When it happens

Trigger: Calling the `add` command with a shape/table type and a parent path whose leading segment names a non-existent sheet, e.g. `add /SheetX shape ...` when the workbook only contains `Sheet1`. Also fires when the sheet was renamed, the wrong file was opened, or the path is malformed (empty leading segment).

Common situations: Typos or casing/whitespace in the sheet name on the command line; sheet renamed between sessions; script operating on a template that has a different sheet layout; copied command from another workbook without adjusting the sheet name.

Related errors

• Sheet not found: {spkSheetName}
• Invalid color value: '{value}'. Expected 6-digit hex RGB (e.
• Invalid source range: {sourceRef}
• Column {startCol} out of range (max: XFD)
• Column {endCol} out of range (max: XFD)

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