iOfficeAI/OfficeCLI · error · ArgumentException

Shape[{shpIndex}] not found in sheet '{sheetNameFromPath}' (

Error message

Shape[{shpIndex}] not found in sheet '{sheetNameFromPath}' (indices are 1-based).

What it means

Thrown for /Sheet/shape[N] when GetShapeNode returns null for that 1-based index (out of range, including shape[0]). Same null-leak fix as picture[N]: previously a bare '!' turned an out-of-range index into an opaque NullReferenceException; now it produces the standard not-found message.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Query.cs:888

            {
                var picIndex = int.Parse(picMatch.Groups[1].Value);
                // GetPictureNode returns null for out-of-range indices (incl.
                // picture[0]); the bare `!` leaked a NullReferenceException as
                // an opaque internal_error instead of the not-found message
                // every sibling element type produces.
                return GetPictureNode(sheetNameFromPath, worksheet, picIndex, path)
                    ?? throw new ArgumentException(
                        $"Picture[{picIndex}] not found in sheet '{sheetNameFromPath}' (indices are 1-based).");
            }

            // Handle shape[N] path segment
            var shpMatch = Regex.Match(cellRef, @"^shape\[(\d+)\]$", RegexOptions.IgnoreCase);
            if (shpMatch.Success)
            {
                var shpIndex = int.Parse(shpMatch.Groups[1].Value);
                // Same null-leak as picture[N] above.
                return GetShapeNode(sheetNameFromPath, worksheet, shpIndex, path)
                    ?? throw new ArgumentException(
                        $"Shape[{shpIndex}] not found in sheet '{sheetNameFromPath}' (indices are 1-based).");
            }


            // If it looks like it could be a malformed cell reference (digits only, etc.), reject it
            if (Regex.IsMatch(cellRef, @"^\d+$"))
                throw new ArgumentException($"Invalid cell reference: '{cellRef}'. Expected format like 'A1', 'B2'.");

            // CONSISTENCY(axis-ref-compat): Excel-style whole-column/row
            // references (B:B, 1:1) are input aliases for col[X]/row[N] —
            // re-dispatch a single-axis span to the canonical path (readback
            // Path stays canonical). Multi-axis spans (B:D) have no single
            // node to return; point at the bracket syntax instead.
            if (TryExpandAxisRef(cellRef) is { } axisSegments)
            {
                if (axisSegments.Count == 1)
                    return Get($"/{sheetNameFromPath}/{axisSegments[0]}", depth);
                throw new ArgumentException(

View on GitHub (pinned to 1ced45e900)

Solutions

1. Use a 1-based index within the shape count.
2. Confirm shapes exist on the sheet before indexing.
3. try/catch(ArgumentException) and degrade to 'no shape'.

Example fix

// before
var shp = handler.Get("/Sheet1/shape[3]"); // throws if <3 shapes

// after
try { var shp = handler.Get("/Sheet1/shape[3]"); }
catch (ArgumentException) { /* shape index invalid */ }

static int? ElementIndex(string cellRef, string element)
{
    var m = Regex.Match(cellRef, $@"^{Regex.Escape(element)}\[(\d+)$", RegexOptions.IgnoreCase);
    return m.Success && int.TryParse(m.Groups[1].Value, out var i) ? i : null;
}

try { return handler.Get("/Sheet1/shape[3]"); }
catch (ArgumentException) { /* shape index invalid */ return null; }

When it happens

Trigger: handler.Get("/Sheet1/shape[3]") on a sheet with fewer than 3 shapes. shape[0]. A sheet with no shapes.

Common situations: Hard-coded shape index after shapes were added or removed. Zero-based indexing. Wrong sheet.

Related errors

• Row break index {rbIdx} out of range (1-{breaks.Count})
• Column break index {cbIdx} out of range (1-{breaks.Count})
• Chart index {caChartIdx} out of range (1-{caAllCharts.Count}
• Chart index {chartIdx} out of range (1-{allCharts.Count})
• Series {seriesIdx} not found (total: {seriesChildren.Count})

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