{"record":{"id":"920c9d77da24a4fa","repo":"iOfficeAI/OfficeCLI","slug":"property-ref-or-range-is-required-for-table","errorCode":null,"errorMessage":"Property 'ref' or 'range' is required for table","messagePattern":"Property 'ref' or 'range' is required for table","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Handlers/Excel/ExcelHandler.Add.Tables.cs","lineNumber":1067,"sourceCode":"                        : fop == FilterOperatorValues.LessThan ? \"lt\"\n                        : fop == FilterOperatorValues.LessThanOrEqual ? \"lte\"\n                        : \"equals\";\n                    node.Format[prefix + op] = val;\n                }\n            }\n        }\n    }\n\n    private string AddTable(string parentPath, string type, InsertPosition? position, Dictionary<string, string> properties)\n    {\n        var index = position?.Index;\n        var tblSegments = parentPath.TrimStart('/').Split('/', 2);\n        var tblSheetName = tblSegments[0];\n        var tblWorksheet = FindWorksheet(tblSheetName)\n            ?? throw new ArgumentException($\"Sheet not found: {tblSheetName}\");\n\n        var rangeRef = (properties.GetValueOrDefault(\"ref\") ?? properties.GetValueOrDefault(\"range\")\n            ?? throw new ArgumentException(\"Property 'ref' or 'range' is required for table\")).ToUpperInvariant();\n\n        // T4 — reject a new table whose ref overlaps any existing table on\n        // the same sheet. Excel silently corrupts the file otherwise.\n        foreach (var existingTdp in tblWorksheet.TableDefinitionParts)\n        {\n            var existing = existingTdp.Table;\n            if (existing?.Reference?.Value is not string existingRef) continue;\n            if (RangesOverlap(rangeRef, existingRef))\n                throw new ArgumentException(\n                    $\"Table ref overlaps existing table '{existing.Name?.Value ?? existing.DisplayName?.Value}' ({existingRef})\");\n        }\n\n\n        var existingTableIds = _doc.WorkbookPart!.WorksheetParts\n            .SelectMany(wp => wp.TableDefinitionParts)\n            .Select(tdp => tdp.Table?.Id?.Value ?? 0);\n        var tableId = existingTableIds.Any() ? existingTableIds.Max() + 1 : 1;\n","sourceCodeStart":1049,"sourceCodeEnd":1085,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Handlers/Excel/ExcelHandler.Add.Tables.cs#L1049-L1085","documentation":"Thrown by AddTable when neither a 'ref' nor a 'range' property is supplied. The table's cell range is mandatory because it defines the <table reference> attribute Excel requires; without it the part would be invalid. The handler accepts either key ('ref' or 'range') for convenience but throws if both are absent.","triggerScenarios":"Calling Add('/Sheet1/table', ...) with properties that omit both ref and range, e.g. only supplying name/style, or misspelling the key as 'refs' or 'rng'.","commonSituations":"Forgetting the range argument, typoing the property name, or assuming the handler auto-detects the used range.","solutions":["Add a 'ref' (or 'range') property with an A1-style range, e.g. ref=A1:D10.","Ensure the key is spelled exactly 'ref' or 'range' (case-insensitive lookup is used).","Verify the range sits inside the target sheet's bounds."],"exampleFix":"// before\nadd /Sheet1/table --prop name=Sales\n// after\nadd /Sheet1/table --prop name=Sales --prop ref=A1:D10","handlingStrategy":"validation","validationCode":"// Ensure a table ref/range is present before Add.\nif (!props.ContainsKey(\"ref\") && !props.ContainsKey(\"range\"))\n    throw new InvalidOperationException(\"Table requires 'ref' or 'range' property.\");","typeGuard":null,"tryCatchPattern":"try { handler.Add(parentPath, \"table\", null, props); }\ncatch (ArgumentException ex) when (ex.Message.Contains(\"'ref' or 'range' is required\"))\n{ /* prompt user for the table range and retry */ }","preventionTips":["Make 'ref' a required field in any table-building UI.","Use the exact key 'ref' or 'range'; the lookup is case-insensitive but spelling matters.","Validate the ref is an A1-style range that fits the sheet before calling Add."],"tags":["excel","table","validation","missing-property"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}