{"record":{"id":"bd47a6fcac0e97c8","repo":"iOfficeAI/OfficeCLI","slug":"table-ref-overlaps-existing-table-existing-name","errorCode":null,"errorMessage":"Table ref overlaps existing table '{existing.Name?.Value ?? existing.DisplayName?.Value}' ({existingRef})","messagePattern":"Table ref overlaps existing table '(.+?)' \\((.+?)\\)","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Handlers/Excel/ExcelHandler.Add.Tables.cs","lineNumber":1076,"sourceCode":"    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\n        var userProvidedName = properties.ContainsKey(\"name\");\n        var tableName = SanitizeTableIdentifier(\n            properties.GetValueOrDefault(\"name\", $\"Table{tableId}\"),\n            userProvided: userProvidedName);\n        // displayName defaults to the (already-sanitized) tableName; if\n        // name was user-provided it flows through verbatim so Excel\n        // shows the same identifier the user asked for.\n        var userProvidedDisplay = properties.ContainsKey(\"displayName\");\n        var displayName = SanitizeTableIdentifier(","sourceCodeStart":1058,"sourceCodeEnd":1094,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Handlers/Excel/ExcelHandler.Add.Tables.cs#L1058-L1094","documentation":"Thrown by AddTable's T4 overlap guard when the new table's range intersects the reference of any existing table on the same sheet. Excel silently corrupts the file when two tables share cells (it cannot reconcile two ListObjects owning the same range), so the handler rejects the overlap up front. The message names the conflicting table and its reference.","triggerScenarios":"Adding a second table whose ref overlaps an existing one on the same sheet, e.g. existing table at A1:C5 and a new table at B2:D6, even partially.","commonSituations":"Re-adding a table without removing the old one, auto-generating ranges that drift into a neighbor, or assuming Excel will merge overlapping tables.","solutions":["Choose a non-overlapping range for the new table.","Remove or relocate the conflicting existing table first.","Query existing tables on the sheet before adding to find a free block."],"exampleFix":"// before (existing table at A1:C5)\nadd /Sheet1/table --prop ref=B2:D6\n// after\nadd /Sheet1/table --prop ref=E1:G5","handlingStrategy":"validation","validationCode":"// Check the candidate ref against existing tables on the target sheet before Add.\nstatic bool OverlapsExistingTable(ExcelHandler h, string sheet, string newRef)\n{\n    foreach (var node in h.Query($\"/{sheet}/table\")) // pseudo: enumerate existing tables\n        if (RangesOverlap(newRef.ToUpperInvariant(), node.Ref.ToUpperInvariant()))\n            return true;\n    return false;\n}","typeGuard":null,"tryCatchPattern":"try { handler.Add(parentPath, \"table\", null, props); }\ncatch (ArgumentException ex) when (ex.Message.Contains(\"overlaps existing table\"))\n{ /* pick a different ref or remove the conflicting table, then retry */ }","preventionTips":["Track table refs per sheet in your orchestration layer to choose free blocks.","Remove or relocate tables before re-adding in idempotent scripts.","Remember overlap is checked on the same sheet only; cross-sheet is fine."],"tags":["excel","table","validation","range-overlap","corruption-prevention"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}