iOfficeAI/OfficeCLI · error · ArgumentException

Sparkline requires 'location' (or 'cell') property (e.g. F1)

Error message

Sparkline requires 'location' (or 'cell') property (e.g. F1)

What it means

Thrown by AddSparkline when no sparkline host-cell location can be resolved. The cell comes from `location=`, then the legacy alias `cell=`, then an optional A1-style tail on the parent path (e.g. `/Sheet1/F1`). If all three are absent the ?? chain throws. The location is required because OOXML xm:sqref must anchor the sparkline to a concrete cell.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Add.Drawings.cs:977

        var index = position?.Index;
        var spkSegments = parentPath.TrimStart('/').Split('/', 2);
        var spkSheetName = spkSegments[0];
        var spkWorksheet = FindWorksheet(spkSheetName)
            ?? throw new ArgumentException($"Sheet not found: {spkSheetName}");

        // CONSISTENCY(canonical-key): 'location'/'dataRange' are canonical;
        // 'cell'/'range'/'data' retained as legacy aliases.
        // R12a: also accept the host cell from the parent path tail
        // (e.g. `add /Sheet1/F1 sparkline --prop dataRange=A1:E1`), mirroring
        // how cell/cf Add derive their target from the path. Explicit
        // location=/cell= still wins.
        var spkPathTail = spkSegments.Length > 1
            && Regex.IsMatch(spkSegments[1], @"^[A-Z]+\d+$", RegexOptions.IgnoreCase)
            ? spkSegments[1].ToUpperInvariant() : null;
        var spkCell = properties.GetValueOrDefault("location")
            ?? properties.GetValueOrDefault("cell")
            ?? spkPathTail
            ?? throw new ArgumentException("Sparkline requires 'location' (or 'cell') property (e.g. F1)");
        var spkRange = properties.GetValueOrDefault("dataRange")
            ?? properties.GetValueOrDefault("datarange")
            ?? properties.GetValueOrDefault("range")
            ?? properties.GetValueOrDefault("data")
            ?? throw new ArgumentException("Sparkline requires 'dataRange' (or 'range'/'data') property (e.g. A1:E1)");

        // OOXML xm:sqref is ST_Sqref (bare cell address, no sheet prefix —
        // sheet is implied by the parent worksheet). Excel silently drops the
        // entire <extLst> on load if sqref carries a sheet prefix.
        spkCell = NormalizeSparklineSqref(spkCell, spkSheetName);
        // A location that is not a real cell reference ("XYZ", empty) wrote a
        // semantically dead <xne:sqref> anchor with no warning; validate the
        // final sqref like every other cell-ref input.
        if (string.IsNullOrWhiteSpace(spkCell)
            || !Regex.IsMatch(spkCell, @"^\$?[A-Za-z]{1,3}\$?\d+(:\$?[A-Za-z]{1,3}\$?\d+)?$"))
            throw new ArgumentException(
                $"Invalid sparkline 'location': '{spkCell}'. Expected a cell reference like F1 (or a range like F1:F5).");
        ParseCellReference(spkCell.Replace("$", "").Split(':')[0]);

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Add `--prop location=F1` (the cell where the sparkline will render).
  2. Alternatively supply `--prop cell=F1` (legacy alias) or put the cell in the path: `add ./book.xlsx /Sheet1/F1 sparkline --prop dataRange=A1:E1`.

Example fix

// before
add ./book.xlsx /Sheet1 sparkline --prop dataRange=A1:E1
// after
add ./book.xlsx /Sheet1 sparkline --prop location=F1 --prop dataRange=A1:E1
Defensive patterns

Strategy: validation

Validate before calling

// Resolve the sparkline host cell with the same precedence the handler uses.
var hostCell = props.GetValueOrDefault("location")
    ?? props.GetValueOrDefault("cell")
    ?? pathTailCell;
if (string.IsNullOrWhiteSpace(hostCell))
    throw new InvalidOperationException("Sparkline requires a host cell (location= or path tail)");

Type guard

static bool HasSparklineLocation(IReadOnlyDictionary<string,string> p, string? pathTail)
    => !string.IsNullOrWhiteSpace(p.GetValueOrDefault("location"))
    || !string.IsNullOrWhiteSpace(p.GetValueOrDefault("cell"))
    || !string.IsNullOrWhiteSpace(pathTail);

Try / catch

try { handler.AddSparkline(...); }
catch (ArgumentException ex) when (ex.Message.Contains("requires 'location'"))
{ /* prompt for the host cell address */ }

Prevention

When it happens

Trigger: Calling `add /Sheet1 sparkline --prop dataRange=A1:E1` with no `location=`/`cell=` and no path tail; or misspelling the key (`loc=`, `target=`). The canonical key is `location`; `cell` is the legacy alias.

Common situations: Forgetting the host cell (a sparkline lives IN a cell, not just over a data range); using an unsupported alias; assuming the dataRange's first cell becomes the host automatically (it does not).

Related errors

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