iOfficeAI/OfficeCLI · error · CliException

unsupported_property

unsupported_property

Error message

{string.Join("\n", parts)}

What it means

Thrown by ExecuteBatchItem for a batch "set" step where the handler rejected EVERY requested property (applied.Count == 0). The per-step verdict flips to failure with Code="unsupported_property" to mirror the standalone set's allFailed semantics (exit 2). The message is the joined "parts": any auto-correct note plus the formatted unsupported-property hints (which typically list valid props). Partial application (some applied, some rejected) does NOT throw.

Source

Thrown at src/officecli/CommandBuilder.cs:1047

                        string? batchScope = handler switch
                        {
                            OfficeCli.Handlers.ExcelHandler => "excel",
                            OfficeCli.Handlers.WordHandler => "word",
                            OfficeCli.Handlers.PowerPointHandler => "pptx",
                            _ => null,
                        };
                        parts.Add(FormatUnsupported(unsupported, batchScope));
                    }
                    // Mirror standalone `set`'s allFailed semantics: if every
                    // requested property was rejected (nothing applied), the
                    // step is a failure, not a successful no-op. Without
                    // this, batch swallowed unsupported_property into an inner
                    // success=true while the same set issued via the
                    // standalone set command returned success=false exit 2.
                    // Per-step verdict flips to false; outer batch envelope
                    // still rides on the existing partial-success rule.
                    if (applied.Count == 0)
                        throw new CliException(string.Join("\n", parts)) { Code = "unsupported_property" };
                }
                return string.Join("\n", parts);
            }
            case "add":
            {
                var parentPath = item.Parent ?? item.Path;
                if (string.IsNullOrEmpty(parentPath))
                    throw new ArgumentException("'add' command requires 'parent' field. Example: {\"command\": \"add\", \"parent\": \"/slide[1]\", \"type\": \"shape\", \"props\": {\"text\": \"Hello\"}}");
                if (string.IsNullOrEmpty(item.Type) && string.IsNullOrEmpty(item.From))
                    throw new ArgumentException("'add' command requires 'type' or 'from' field. Example: {\"command\": \"add\", \"parent\": \"/\", \"type\": \"slide\"}");
                InsertPosition? pos = null;
                if (item.Index.HasValue) pos = InsertPosition.AtIndex(item.Index.Value);
                else if (!string.IsNullOrEmpty(item.After)) pos = InsertPosition.AfterElement(item.After);
                else if (!string.IsNullOrEmpty(item.Before)) pos = InsertPosition.BeforeElement(item.Before);

                if (!string.IsNullOrEmpty(item.From))
                {
                    var resultPath = handler.CopyFrom(item.From, parentPath, pos);

View on GitHub (pinned to 1ced45e900)

Solutions

1. Read the message: it includes 'valid props:' for the scope — replace each bad key with a listed one.
2. Fix typos so they are within autocorrect range (Levenshtein distance 1) or exact.
3. If you genuinely need an unsupported prop, use raw-set as the documented escape hatch.
4. Confirm the props match the handler type for the target path (excel/word/pptx).

Example fix

// before
{"command":"set","path":"/sheet[1]/row[1]","props":{"colour":"red"}}
// after
{"command":"set","path":"/sheet[1]/row[1]","props":{"color":"red"}}

// Validate prop names against the handler's supported set before submitting.
var supported = handler.SupportedProps(path);  // pseudocode
var bad = props.Keys.Except(supported, StringComparer.OrdinalIgnoreCase).ToList();
if (bad.Count == props.Count) /* all will be rejected — fix or raw-set */

try { ExecuteBatchItem(handler, item, json); }
catch (CliException ex) when (ex.Code == "unsupported_property")
{ /* parse 'valid props:' hint, fix keys, retry or raw-set */ }

When it happens

Trigger: {"command":"set","path":"/sheet[1]/row[1]","props":{"colour":"red"}} where "colour" is not a unique distance-1 typo and nothing applies; setting Excel-only props on a path the handler does not support; version-specific prop names.

Common situations: Wrong prop vocabulary for the document type (e.g. PPT props on an Excel path); typos beyond autocorrect range; deprecated/renamed props after an upgrade; copy of a step across handlers without adapting prop names.

Related errors

• 'set' command requires 'path' field. Example: {"command": "s
• 'set' command requires 'props' field with at least one key=v
• invalid_input
• Path not found: {path}
• 'query' command requires 'selector' field. Example: {"comman

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