iOfficeAI/OfficeCLI · error · ArgumentException

Unsupported cell property: {string.Join("; ", cellHintMessag

Error message

Unsupported cell property: {string.Join("; ", cellHintMessages)}

What it means

Before the style filter runs, AddCell checks each property key against CellPropHints — keys that are genuinely ambiguous in cell context (e.g. `color`, which could be font.color or fill; `path`, which is not a cell property). If any ambiguous key is present, it throws listing all hints rather than silently dropping the key. Without this, Add would silently drop the key while Set loudly rejects it — inconsistent, and the caller's intent would be lost.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Add.Cells.cs:914

                ?? properties.GetValueOrDefault("image.alt");
            if (inCellAlt != null) Core.ParseHelpers.ValidateXmlText(inCellAlt, "alt");
            SetInCellImage(cell, inCellImg, inCellAlt);
        }

        // CONSISTENCY(cell-prop-hints): mirror Set's CellPropHints check
        // here. Before the style filter runs, flag any ambiguous flat
        // keys (e.g. `color` — is it font.color or fill?) as unsupported.
        // Without this, Add silently drops the key while Set loudly
        // rejects it — inconsistent, and the caller's intent is lost.
        var cellHintMessages = new List<string>();
        foreach (var (key, _) in properties)
        {
            var hint = CellPropHints.TryGetHint(key);
            if (hint != null)
                cellHintMessages.Add(hint);
        }
        if (cellHintMessages.Count > 0)
            throw new ArgumentException(
                "Unsupported cell property: " + string.Join("; ", cellHintMessages));

        // Apply style properties if any. Use TryGetValue per key so the
        // TrackingPropertyDictionary comparer marks each style key as
        // accessed — bare foreach over the upcast Dictionary<,> base type
        // bypasses the recording GetEnumerator override and leaves
        // legitimately-consumed keys (bold, align, color, ...) reported
        // as UNSUPPORTED while their values silently take effect.
        var cellStyleProps = new Dictionary<string, string>();
        foreach (var key in properties.Keys.ToList())
        {
            if (ExcelStyleManager.IsStyleKey(key) && properties.TryGetValue(key, out var val))
                cellStyleProps[key] = val;
        }
        if (cellStyleProps.Count > 0)
        {
            var cellWbPart = _doc.WorkbookPart
                ?? throw new InvalidOperationException("Workbook not found");

View on GitHub (pinned to 1ced45e900)

Solutions

1. For text color use font.color; for background color use fill (or its aliases).
2. For the cell address use 'ref' (or 'address'), not 'path'.
3. Remove the ambiguous key and replace it with the specific namespaced key the error hint suggests.

Example fix

// before
handler.Add("/Sheet1/A1", "cell", null, new() { ["color"] = "FF0000", ["value"] = "x" });
// after
handler.Add("/Sheet1/A1", "cell", null, new() { ["font.color"] = "FF0000", ["value"] = "x" });

static readonly HashSet<string> Ambiguous = new(StringComparer.OrdinalIgnoreCase){"color","path"};
foreach (var k in props.Keys)
    if (Ambiguous.Contains(k))
        throw new ArgumentException($"'{k}' is ambiguous in cell context; use font.color/fill or ref/address");

static bool IsUnambiguousCellKey(string k) =>
    !k.Equals("color", StringComparison.OrdinalIgnoreCase)
    && !k.Equals("path", StringComparison.OrdinalIgnoreCase);

try { h.Add(parentPath, "cell", pos, props); }
catch (ArgumentException ex) when (ex.Message.StartsWith("Unsupported cell property"))
{ /* replace 'color' with font.color/fill, 'path' with ref/address, and retry */ }

When it happens

Trigger: Add("/Sheet1/A1","cell",pos,{["color"]="FF0000", ...}); props contains 'path=...'; any prop key present in CellPropHints.AmbiguousKeys (currently 'color' and 'path').

Common situations: Carrying flat keys over from PPT/Word run properties where 'color' means text color; using 'path' (a picture/ole key) on a cell; copy-pasting a prop bag from another element type.

Related errors

• Unrecognized cell parent path segment '{cellSegments[1]}'. E
• Invalid cell reference: '{cellRef}'
• --prop shift={shiftVal} not valid for add cell. Use 'right'
• Cannot store '{properties.GetValueOrDefault("value") ?? prop
• Literal braces '{...}' around a formula create an Excel-reje

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