iOfficeAI/OfficeCLI · error · ArgumentException

Invalid merge ref '{newRangeRef}': path is a single-target l

Error message

Invalid merge ref '{newRangeRef}': path is a single-target locator (no comma). Move ranges to a prop value, e.g. `set ... '/Sheet1' --prop merge={newRangeRef}`.

What it means

A merge-cell ref passed as a path target contained a comma, which denotes a multi-target locator. Merge operations accept a single A1 cell or A1:B2 range per target; comma-separated lists belong in a prop value, not the path. The library rejects commas before any further parsing.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Helpers.Validation.cs:466

    // "found a problem" repair dialog, but the OOXML SDK happily
    // appends them. Mirrors the T4 overlap-throws pattern used by
    // tables and AutoFilter+table.
    // - Exact-match ref: no-op (idempotent re-Add stays consistent
    //   with prior dedup behavior).
    // - Geometric overlap with a non-identical range: throw.
    // - Otherwise: append.
    private static readonly System.Text.RegularExpressions.Regex SingleMergeRefPattern =
        new(@"^[A-Z]+[0-9]+(:[A-Z]+[0-9]+)?$",
            System.Text.RegularExpressions.RegexOptions.Compiled);

    // CONSISTENCY(merge-comma): callers should run this BEFORE creating an
    // empty <mergeCells> container, so a rejected ref doesn't leave a
    // schema-invalid empty container in the saved file.
    private static void ValidateMergeRefLiteral(string newRangeRef)
    {
        var refUpper = newRangeRef.ToUpperInvariant();
        if (refUpper.Contains(','))
            throw new ArgumentException(
                $"Invalid merge ref '{newRangeRef}': path is a single-target locator (no comma). " +
                $"Move ranges to a prop value, e.g. `set ... '/Sheet1' --prop merge={newRangeRef}`.");
        if (!SingleMergeRefPattern.IsMatch(refUpper))
            throw new ArgumentException(
                $"Invalid merge ref '{newRangeRef}': must be a single A1 cell (e.g. 'B2') or A1:B2 range (e.g. 'B4:E4').");
        // CONSISTENCY(merge-orientation): the ref must read top-left to
        // bottom-right. Z1:A1 / A10:A1 / B2:A1 (any reversed orientation)
        // were silently accepted; Excel itself only writes the canonical
        // form, so callers passing a reversed pair almost certainly typo'd.
        // Reject with a hint to swap, mirroring the orientation guard the
        // sheetShift normalizer applies after the fact (ExcelHandler.Set.cs
        // L1918) and matching how other range-bearing props (validation,
        // table, autofilter) demand canonical orientation up front.
        var colonIdx = refUpper.IndexOf(':');
        if (colonIdx > 0)
        {
            var lhs = refUpper.Substring(0, colonIdx);
            var rhs = refUpper.Substring(colonIdx + 1);

View on GitHub (pinned to 1ced45e900)

Solutions

Move the comma-separated ranges into the --prop merge value as the message suggests.
Issue one merge call per range instead of packing them into the path.
Check the CLI's path-vs-prop distinction in the docs before batching.

Example fix

# before
officecli set /Sheet1/A1:B2,C3:D4 --prop merge=true

# after
officecli set /Sheet1 --prop merge=A1:B2,C3:D4

Defensive patterns

Strategy: validation

Validate before calling

static string SingleMergeTarget(string path) {
    if (path.Contains(','))
        throw new InvalidOperationException("Pass comma-separated merge ranges via --prop merge=...");
    return path;
}

Try / catch

try { cli.Set($"/Sheet1/{target}", merge: true); }
catch (ArgumentException ex) when (ex.Message.Contains("no comma")) {
    cli.Set("/Sheet1", prop: $"merge={target}");
}

Prevention

Keep the path/target vs prop-value distinction explicit in your CLI wrappers.
Batch merge ranges through the prop channel, not the path.

When it happens

Trigger: Calling a set/merge API with a path target like '/Sheet1/A1:B2,C3:D4' — the comma trips ValidateMergeRefLiteral immediately.

Common situations: Trying to merge several ranges in one CLI invocation; passing a range list where a single target is expected; misreading the path grammar.

Related errors

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