iOfficeAI/OfficeCLI · error · ArgumentException

Merge range '{refUpper}' overlaps existing merged range '{er

Error message

Merge range '{refUpper}' overlaps existing merged range '{er}'. Excel rejects overlapping mergeCell entries.

What it means

InsertMergeCellCheckedCore rejects a mergeCell whose range geometrically overlaps an existing merged range -- Excel itself rejects overlapping merges with a repair dialog, so this guard fails fast. The check is idempotent: an identical range is a silent no-op; only a true rectangle intersection throws. RangesOverlap is case-insensitive on the A1 refs. Fires from the Set/Add merge path (InsertMergeCellChecked wraps it and removes a now-empty <mergeCells> shell on failure).

Source

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

            // corrupted a previously-fine file. Remove the empty shell
            // before rethrowing.
            if (!mergeCells.Elements<MergeCell>().Any() && mergeCells.Parent != null)
                mergeCells.Remove();
            throw;
        }
    }

    private static void InsertMergeCellCheckedCore(MergeCells mergeCells, string newRangeRef, WorksheetPart? worksheetPart = null)
    {
        ValidateMergeRefLiteral(newRangeRef);
        var refUpper = newRangeRef.ToUpperInvariant();
        foreach (var existing in mergeCells.Elements<MergeCell>())
        {
            if (existing.Reference?.Value is not string er) continue;
            var erUpper = er.ToUpperInvariant();
            if (string.Equals(erUpper, refUpper, StringComparison.Ordinal)) return; // idempotent
            if (RangesOverlap(refUpper, erUpper))
                throw new ArgumentException(
                    $"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)";

View on GitHub (pinned to 1ced45e900)

Solutions

1. Pick a disjoint range that does not intersect any existing merge.
2. Unmerge the conflicting existing range first, then re-merge the union.
3. Rely on idempotency: re-applying the exact same range is a no-op.
4. Enumerate current merges before applying and compute non-overlapping tiles.

Example fix

// before -- A2 is already inside the A1:B2 merge
set sheet!A1:B2 merge=true
set sheet!A2:B3 merge=true  // throws: overlaps A1:B2

// after -- unmerge first, then merge the union
set sheet!A1:B2 merge=false
set sheet!A1:B3 merge=true

// Before merging, ensure no existing merge overlaps the new range.
// (Use the same RangesOverlap logic the library uses; re-derive existing merges via Get.)
var existing = handler.GetExistingMerges(sheet); // your helper
foreach (var r in existing)
    if (RangesOverlap(newRange, r) && !string.Equals(newRange, r, StringComparison.OrdinalIgnoreCase))
        throw new InvalidOperationException($"Would overlap existing merge {r}");

When it happens

Trigger: Merge A1:B2 then merge A2:B3 (shared cell A2/B2); merge B1:C1 then merge A1:B1 (shared B1); re-merge a sub-range of an existing merge that is not identical.

Common situations: Building a header layout incrementally and overlapping a prior merge; dump replay where the source had overlapping merges after manual editing; union of two adjacent merges that share an edge cell.

Related errors

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

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