iOfficeAI/OfficeCLI · error · ArgumentException

'name' property is required for namedrange

Error message

'name' property is required for namedrange

What it means

Thrown when adding a named range and no name can be resolved. The name comes from the `name=` property, or, if absent, from a `namedrange[Name]` index capture in the parent path (only if the captured token is not a pure integer). If both are empty/null the throw fires. A defined name without an identifier is invalid OOXML, so this is a hard precondition.

Source

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

        // still wins on mismatch, to keep other `/namedrange[N]` int
        // indexing semantics elsewhere in the handler usable as-is).
        var pathNrName = "";
        {
            var mNr = System.Text.RegularExpressions.Regex.Match(
                parentPath, @"^/namedrange\[([^\]]+)\]/?$",
                System.Text.RegularExpressions.RegexOptions.IgnoreCase);
            if (mNr.Success)
            {
                var captured = mNr.Groups[1].Value;
                // Only treat as a name if it is not a pure integer
                // (preserves existing `/namedrange[1]` semantics).
                if (!int.TryParse(captured, out _))
                    pathNrName = captured;
            }
        }
        var nrName = properties.GetValueOrDefault("name", pathNrName);
        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)

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Add `--prop name=MyRange`.
  2. Or use a path capture like `/namedrange[MyRange]` (the non-integer bracket content is promoted to the name).

Example fix

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

Strategy: validation

Validate before calling

// Resolve the name the way the handler does before calling add.
var name = props.GetValueOrDefault("name") ?? PathDerivedName(path);
if (string.IsNullOrEmpty(name))
    throw new InvalidOperationException("namedrange requires a name (name= or /namedrange[Name])");

Type guard

static bool HasNamedRangeName(IReadOnlyDictionary<string,string> p, string? pathName)
    => !string.IsNullOrEmpty(p.GetValueOrDefault("name"))
    || !string.IsNullOrEmpty(pathName);

Try / catch

try { handler.AddNamedRange(...); }
catch (ArgumentException ex) when (ex.Message.Contains("'name' property is required"))
{ /* prompt for the identifier */ }

Prevention

When it happens

Trigger: Calling `add /namedrange --type namedrange --prop ref=Sheet1!A1` with no `name=` and no path-derived name. Also when the path is `/namedrange[1]` (the bracketed index is an integer, so it is NOT promoted to a name) and no `name=` is given.

Common situations: Forgetting the name; assuming the index in `namedrange[1]` becomes the name (it does not — only non-integer captures do); using `title=` or `id=` instead of `name=`.

Related errors

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