{"record":{"id":"b161fa59221b7850","repo":"iOfficeAI/OfficeCLI","slug":"shape-shpindex-not-found-in-sheet-sheetnamefr","errorCode":null,"errorMessage":"Shape[{shpIndex}] not found in sheet '{sheetNameFromPath}' (indices are 1-based).","messagePattern":"Shape\\[(.+?)\\] not found in sheet '(.+?)' \\(indices are 1-based\\)\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Handlers/Excel/ExcelHandler.Query.cs","lineNumber":888,"sourceCode":"            {\n                var picIndex = int.Parse(picMatch.Groups[1].Value);\n                // GetPictureNode returns null for out-of-range indices (incl.\n                // picture[0]); the bare `!` leaked a NullReferenceException as\n                // an opaque internal_error instead of the not-found message\n                // every sibling element type produces.\n                return GetPictureNode(sheetNameFromPath, worksheet, picIndex, path)\n                    ?? throw new ArgumentException(\n                        $\"Picture[{picIndex}] not found in sheet '{sheetNameFromPath}' (indices are 1-based).\");\n            }\n\n            // Handle shape[N] path segment\n            var shpMatch = Regex.Match(cellRef, @\"^shape\\[(\\d+)\\]$\", RegexOptions.IgnoreCase);\n            if (shpMatch.Success)\n            {\n                var shpIndex = int.Parse(shpMatch.Groups[1].Value);\n                // Same null-leak as picture[N] above.\n                return GetShapeNode(sheetNameFromPath, worksheet, shpIndex, path)\n                    ?? throw new ArgumentException(\n                        $\"Shape[{shpIndex}] not found in sheet '{sheetNameFromPath}' (indices are 1-based).\");\n            }\n\n\n            // If it looks like it could be a malformed cell reference (digits only, etc.), reject it\n            if (Regex.IsMatch(cellRef, @\"^\\d+$\"))\n                throw new ArgumentException($\"Invalid cell reference: '{cellRef}'. Expected format like 'A1', 'B2'.\");\n\n            // CONSISTENCY(axis-ref-compat): Excel-style whole-column/row\n            // references (B:B, 1:1) are input aliases for col[X]/row[N] —\n            // re-dispatch a single-axis span to the canonical path (readback\n            // Path stays canonical). Multi-axis spans (B:D) have no single\n            // node to return; point at the bracket syntax instead.\n            if (TryExpandAxisRef(cellRef) is { } axisSegments)\n            {\n                if (axisSegments.Count == 1)\n                    return Get($\"/{sheetNameFromPath}/{axisSegments[0]}\", depth);\n                throw new ArgumentException(","sourceCodeStart":870,"sourceCodeEnd":906,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Handlers/Excel/ExcelHandler.Query.cs#L870-L906","documentation":"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.","triggerScenarios":"handler.Get(\"/Sheet1/shape[3]\") on a sheet with fewer than 3 shapes. shape[0]. A sheet with no shapes.","commonSituations":"Hard-coded shape index after shapes were added or removed. Zero-based indexing. Wrong sheet.","solutions":["Use a 1-based index within the shape count.","Confirm shapes exist on the sheet before indexing.","try/catch(ArgumentException) and degrade to 'no shape'."],"exampleFix":"// before\nvar shp = handler.Get(\"/Sheet1/shape[3]\"); // throws if <3 shapes\n\n// after\ntry { var shp = handler.Get(\"/Sheet1/shape[3]\"); }\ncatch (ArgumentException) { /* shape index invalid */ }","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"static int? ElementIndex(string cellRef, string element)\n{\n    var m = Regex.Match(cellRef, $@\"^{Regex.Escape(element)}\\[(\\d+)$\", RegexOptions.IgnoreCase);\n    return m.Success && int.TryParse(m.Groups[1].Value, out var i) ? i : null;\n}","tryCatchPattern":"try { return handler.Get(\"/Sheet1/shape[3]\"); }\ncatch (ArgumentException) { /* shape index invalid */ return null; }","preventionTips":["Shape indices are 1-based — there is no index 0.","Confirm shapes exist on the sheet before indexing.","Don't reuse a cached index after shapes are added or removed."],"tags":["excel","shape","path-index","argument-exception"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}