iOfficeAI/OfficeCLI · error · ArgumentException

Sparkline requires 'dataRange' (or 'range'/'data') property

Error message

Sparkline requires 'dataRange' (or 'range'/'data') property (e.g. A1:E1)

What it means

Thrown by AddSparkline when no source data range can be resolved. The data range is looked up under canonical `dataRange`, then aliases `datarange`, `range`, `data`; if none are present the ?? chain throws. The data range is required because a sparkline with no series data is meaningless and would write a dead XML element.

Source

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

        // 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]);

        // Determine sparkline type
        // bt-2: reject invalid types (e.g. "bar") instead of silently mapping
        // to Line. Sparkline OOXML has exactly three types: line/column/stacked
        // (winloss is an alias for stacked).

View on GitHub (pinned to 1ced45e900)

Solutions

1. Add `--prop dataRange=A1:E1` (the series the sparkline visualizes).
2. Alternatively use alias `range=` or `data=`.

Example fix

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

var dataRange = props.GetValueOrDefault("dataRange")
    ?? props.GetValueOrDefault("datarange")
    ?? props.GetValueOrDefault("range")
    ?? props.GetValueOrDefault("data");
if (string.IsNullOrWhiteSpace(dataRange))
    throw new InvalidOperationException("Sparkline requires a data range (dataRange=)");

static bool HasSparklineDataRange(IReadOnlyDictionary<string,string> p)
    => new[]{"dataRange","datarange","range","data"}
        .Any(k => !string.IsNullOrWhiteSpace(p.GetValueOrDefault(k)));

try { handler.AddSparkline(...); }
catch (ArgumentException ex) when (ex.Message.Contains("requires 'dataRange'"))
{ /* prompt for the source data range */ }

When it happens

Trigger: Calling `add /Sheet1/F1 sparkline --prop location=F1` with no data range key, or using an unsupported alias like `source=` or `values=`. The canonical key is `dataRange`.

Common situations: Assuming the sparkline infers its data from the host cell; misspelling `dataRange` as `data-range` or `dataset`; providing only the type/color props.

Related errors

• Sparkline requires 'location' (or 'cell') property (e.g. F1)
• Sheet not found: {spkSheetName}
• Invalid sparkline 'location': '{spkCell}'. Expected a cell r
• Invalid sparkline type: '{spkTypeStr}'. Valid values: line,
• Unknown displayEmptyCellsAs value '{deca}'. Valid: gap, span

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