iOfficeAI/OfficeCLI · error · ArgumentException

Table ref overlaps existing table '{existing.Name?.Value ??

Error message

Table ref overlaps existing table '{existing.Name?.Value ?? existing.DisplayName?.Value}' ({existingRef})

What it means

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.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Add.Tables.cs:1076

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

        var rangeRef = (properties.GetValueOrDefault("ref") ?? properties.GetValueOrDefault("range")
            ?? throw new ArgumentException("Property 'ref' or 'range' is required for table")).ToUpperInvariant();

        // T4 — reject a new table whose ref overlaps any existing table on
        // the same sheet. Excel silently corrupts the file otherwise.
        foreach (var existingTdp in tblWorksheet.TableDefinitionParts)
        {
            var existing = existingTdp.Table;
            if (existing?.Reference?.Value is not string existingRef) continue;
            if (RangesOverlap(rangeRef, existingRef))
                throw new ArgumentException(
                    $"Table ref overlaps existing table '{existing.Name?.Value ?? existing.DisplayName?.Value}' ({existingRef})");
        }


        var existingTableIds = _doc.WorkbookPart!.WorksheetParts
            .SelectMany(wp => wp.TableDefinitionParts)
            .Select(tdp => tdp.Table?.Id?.Value ?? 0);
        var tableId = existingTableIds.Any() ? existingTableIds.Max() + 1 : 1;

        var userProvidedName = properties.ContainsKey("name");
        var tableName = SanitizeTableIdentifier(
            properties.GetValueOrDefault("name", $"Table{tableId}"),
            userProvided: userProvidedName);
        // displayName defaults to the (already-sanitized) tableName; if
        // name was user-provided it flows through verbatim so Excel
        // shows the same identifier the user asked for.
        var userProvidedDisplay = properties.ContainsKey("displayName");
        var displayName = SanitizeTableIdentifier(

View on GitHub (pinned to 1ced45e900)

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.

Example fix

// before (existing table at A1:C5)
add /Sheet1/table --prop ref=B2:D6
// after
add /Sheet1/table --prop ref=E1:G5

Defensive patterns

Strategy: validation

Validate before calling

// Check the candidate ref against existing tables on the target sheet before Add.
static bool OverlapsExistingTable(ExcelHandler h, string sheet, string newRef)
{
    foreach (var node in h.Query($"/{sheet}/table")) // pseudo: enumerate existing tables
        if (RangesOverlap(newRef.ToUpperInvariant(), node.Ref.ToUpperInvariant()))
            return true;
    return false;
}

Try / catch

try { handler.Add(parentPath, "table", null, props); }
catch (ArgumentException ex) when (ex.Message.Contains("overlaps existing table"))
{ /* pick a different ref or remove the conflicting table, then retry */ }

Prevention

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.

When it happens

Trigger: 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.

Common situations: Re-adding a table without removing the old one, auto-generating ranges that drift into a neighbor, or assuming Excel will merge overlapping tables.

Related errors

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