iOfficeAI/OfficeCLI · error · ArgumentException

Merge range '{refUpper}' overlaps ListObject table '{tblName

Error message

Merge range '{refUpper}' overlaps ListObject table '{tblName}' (ref '{tblRef}'). Excel does not allow merging cells inside a table range. Convert the table to a normal range first.

What it means

InsertMergeCellCheckedCore rejects a merge range that intersects a ListObject (table) range: Excel opens such files with a 'found a problem' repair dialog, so this prevents silent corruption. It iterates worksheetPart.TableDefinitionParts and tests each Table.Reference for overlap with the merge. Only fires when worksheetPart is supplied (the Set merge path passes it). The error names the offending table and its reference.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Helpers.Cell.cs:305

                    $"Merge range '{refUpper}' overlaps existing merged range '{er}'. " +
                    $"Excel rejects overlapping mergeCell entries.");
        }
        // BUG-R2-table-merge BUG-5: Excel forbids mergeCell entries that
        // intersect a ListObject table range — files saved with such a
        // merge open with a "found a problem" repair dialog. Reject up
        // front so callers see a clear error instead of file corruption.
        if (worksheetPart != null)
        {
            foreach (var tdp in worksheetPart.TableDefinitionParts)
            {
                var tblRef = tdp.Table?.Reference?.Value;
                if (string.IsNullOrEmpty(tblRef)) continue;
                if (RangesOverlap(refUpper, tblRef.ToUpperInvariant()))
                {
                    var tblName = tdp.Table?.Name?.Value
                        ?? tdp.Table?.DisplayName?.Value
                        ?? "(unnamed)";
                    throw new ArgumentException(
                        $"Merge range '{refUpper}' overlaps ListObject table '{tblName}' (ref '{tblRef}'). " +
                        "Excel does not allow merging cells inside a table range. Convert the table to a normal range first.");
                }
            }
        }
        // Advisory only — a multi-million-cell merge is legal OOXML and
        // validates green, but real Excel stalls for minutes opening it
        // (empirically: 16384x1 renders in seconds; 1024x100000 hangs past
        // a 120s render timeout). Warn so the caller knows the file may be
        // unusable in practice; do not reject (lenient-input convention).
        if (TryParseRangeDims(refUpper, out var mergeRows, out var mergeCols)
            && (long)mergeRows * mergeCols > 10_000_000)
        {
            Console.Error.WriteLine(
                $"Warning: merge range '{refUpper}' spans {(long)mergeRows * mergeCols:N0} cells; " +
                "real Excel can hang for minutes opening merges this large.");
        }
        mergeCells.AppendChild(new MergeCell { Reference = refUpper });

View on GitHub (pinned to 1ced45e900)

Solutions

1. Convert the table to a normal range first (Excel: Table Design > Convert to Range), then merge.
2. Merge cells outside the table's Reference rectangle.
3. Remove the table if merging within its area is essential.
4. Check table ranges (worksheetPart.TableDefinitionParts) before issuing the merge.

Example fix

// before -- B2:B3 lies inside table 'SalesData' (A1:E10)
set sheet!B2:B3 merge=true  // throws: overlaps ListObject

// after -- merge outside the table, or remove the table first
set sheet!G2:G3 merge=true

// Before merging, confirm the range does not intersect any table range.
foreach (var tbl in handler.GetTablesOnSheet(sheet)) // your helper returning refs
    if (RangesOverlap(newRange, tbl.Reference))
        throw new InvalidOperationException($"Merge intersects table {tbl.Name} ({tbl.Reference}); convert to range first.");

When it happens

Trigger: Table defined over A1:C5, then merge B2:B3 (inside the table); merge any cell range that intersects a table's Reference rectangle.

Common situations: Treating a table region like a normal range and merging header cells inside it; forgetting to convert an imported table to a normal range before merging.

Related errors

• Defined name '{nrName}' collides with the table name '{exist
• Unknown totals-row function '{tok}'. Valid: sum, average, co
• Merge range '{refUpper}' overlaps existing merged range '{er
• Property 'sqref' (or 'range'/'ref') is required for validati
• Sheet not found: {tblSheetName}

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