iOfficeAI/OfficeCLI · error · ArgumentException

Invalid defined-name '{nrName}': name parses as a cell refer

Error message

Invalid defined-name '{nrName}': name parses as a cell reference; choose a different name.

What it means

Thrown when the resolved name parses as a valid A1-style cell reference (LooksLikeCellReference returns true). A defined name that looks like a cell address (e.g. `A1`, `TBL1`, `XFD1048576` within grid bounds) is ambiguous with a cell address, and Excel refuses the file. The check validates the column letters against the real grid (1..16384) and the row against 1..1048576, so `A1` and `IV999` fail but `AAAA1` (column beyond XFD) would not.

Source

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

        if (string.IsNullOrEmpty(nrName))
            throw new ArgumentException("'name' property is required for namedrange");
        // Per OOXML §18.2.5: defined-name identifiers must start with
        // letter/underscore/backslash, contain only letter/digit/
        // underscore/period/backslash, and must not parse as a cell
        // reference. Otherwise Excel rejects the file with 0x800A03EC.
        // "Letter" is any Unicode letter (\p{L}) — Excel accepts CJK/
        // Cyrillic/etc. names; the previous ASCII-only class falsely
        // rejected them. Emoji/symbols stay rejected (not \p{L}).
        if (!System.Text.RegularExpressions.Regex.IsMatch(nrName, @"^[\p{L}_\\][\p{L}\p{N}_\\.]*$"))
            throw new ArgumentException($"Invalid defined-name '{nrName}': must start with a letter/underscore and contain only letters, digits, underscores, or periods (no spaces).");
        // Excel caps defined-name identifier length at 255 characters; longer
        // names are silently truncated on open (or the file is rejected with
        // 0x800A03EC depending on host). Refuse up front instead of letting
        // a 256+ char name land on disk and round-trip-differ on re-open.
        if (nrName.Length > 255)
            throw new ArgumentException($"Invalid defined-name '{nrName}': length {nrName.Length} exceeds the Excel 255-character limit.");
        if (LooksLikeCellReference(nrName))
            throw new ArgumentException($"Invalid defined-name '{nrName}': name parses as a cell reference; choose a different name.");
        // R39-5: Excel reserves the single letters R and C (case-insensitive)
        // because they collide with R1C1 reference notation. Excel rejects
        // the file with 0x800A03EC if either is used as a defined name.
        if (nrName.Length == 1 && (nrName[0] == 'R' || nrName[0] == 'r' || nrName[0] == 'C' || nrName[0] == 'c'))
            throw new ArgumentException($"Invalid defined-name '{nrName}': single letter 'R' / 'C' is reserved by Excel for R1C1 reference notation; choose a different name.");
        // `refersTo` is the common Excel-documented alias for `ref`;
        // silently map it so users don't end up with an empty
        // <x:definedName/> that corrupts the file.
        var refVal = properties.GetValueOrDefault("ref",
            properties.GetValueOrDefault("refersTo",
                properties.GetValueOrDefault("formula", "")));
        // R15/bt-2: reject up-front when the required ref/refersTo/formula
        // value is missing so an empty <x:definedName/> never gets written
        // (the resulting zombie polluted the workbook and broke later Set
        // calls). Unsupported aliases like `range=` previously silently
        // landed here as empty and produced the zombie.
        if (string.IsNullOrEmpty(refVal))
            throw new ArgumentException("'ref' (or 'refersTo' / 'formula') property is required for namedrange");

View on GitHub (pinned to 1ced45e900)

Solutions

Choose a name that is not parseable as a cell address, e.g. prefix it: `Range_A1`, `CellA1`, or use a word like `TotalA1`.
If you need a single-letter-ish name, add an underscore or a second word so it no longer matches ^[A-Za-z]{1,3}\d+$.

Example fix

// before
add ./book.xlsx /namedrange --type namedrange --prop name=A1 --prop ref=Sheet1!A1:B1
// after
add ./book.xlsx /namedrange --type namedrange --prop name=RangeA1 --prop ref=Sheet1!A1:B1

Defensive patterns

Strategy: validation

Validate before calling

if (LooksLikeCellReference(name))
    throw new InvalidOperationException(
        $"Defined-name '{name}' looks like a cell reference; pick another");

Type guard

static bool LooksLikeCellReference(string? s)
{
    if (string.IsNullOrEmpty(s)) return false;
    var m = System.Text.RegularExpressions.Regex.Match(s, @"^\$?([A-Za-z]{1,3})\$?([0-9]+)$");
    if (!m.Success) return false;
    int col = 0; foreach (var ch in m.Groups[1].Value.ToUpperInvariant()) col = col*26 + (ch-'A'+1);
    return col is >= 1 and <= 16384
        && long.TryParse(m.Groups[2].Value, out var row) && row is >= 1 and <= 1048576;
}

Try / catch

try { handler.AddNamedRange(...); }
catch (ArgumentException ex) when (ex.Message.Contains("parses as a cell reference"))
{ /* prefix or rename the identifier */ }

Prevention

Avoid 1-3-letter-plus-digits names that fall inside the grid (A1, IV999).
Prefix short names (Range_A1) to disambiguate from cell addresses.

When it happens

Trigger: Passing `name=A1`, `name=SUM1`, `name=TBL1`, or any 1-3-letter+digits token that falls inside the grid. Common when a desired name happens to spell like a cell.

Common situations: Naming a range after its first cell (`A1`); short names like `C5`; names that coincidentally match a cell pattern after uppercase normalization.

Related errors

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