iOfficeAI/OfficeCLI · error · InvalidOperationException

Unknown command: '{item.Command}'. Valid commands: get, quer

Error message

Unknown command: '{item.Command}'. Valid commands: get, query, set, add, remove, move, swap, view, raw, validate.{batchHint}

What it means

Thrown in the default branch when item.Command is non-empty but matches no recognized verb. The code adds a smart 'batchHint': if the command contains whitespace it is almost certainly a whole CLI line stuffed into the verb field (e.g. 'add /slide[1] --type shape'), and the hint tells the caller to use the bare verb plus sibling fields. Otherwise the hint points at 'help batch'.

Source

Thrown at src/officecli/CommandBuilder.cs:1258

                return string.Join("\n", lines);
            }
            default:
                if (string.IsNullOrEmpty(item.Command))
                    throw new InvalidOperationException(
                        "Batch item missing required 'command' field. " +
                        "Valid commands: get, query, set, add, remove, move, view, raw, validate. " +
                        "Example: {\"command\": \"set\", \"path\": \"/Sheet1/A1\", \"props\": {\"value\": \"hello\"}}");
                // A "command" containing whitespace is almost always a whole CLI
                // line stuffed into the verb field (e.g. "add /slide[1] --type
                // shape --prop ...") — the single most common batch-item mistake.
                // Diagnose it specifically and point at the item schema; a plain
                // unknown verb just gets the schema pointer.
                var batchHint = item.Command.Any(char.IsWhiteSpace)
                    ? " — that looks like a whole CLI line placed in \"command\". Use the bare verb only and put the"
                      + " rest in sibling fields, e.g. {\"command\":\"add\",\"parent\":\"/slide[1]\",\"type\":\"shape\","
                      + "\"props\":{...}}. Run `help batch` for the item schema."
                    : " Run `help batch` for the JSON item schema.";
                throw new InvalidOperationException($"Unknown command: '{item.Command}'. Valid commands: get, query, set, add, remove, move, swap, view, raw, validate.{batchHint}");
        }
    }

    private static Dictionary<string, string> ParsePropsArray(string[]? props)
    {
        var dict = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
        foreach (var prop in props ?? Array.Empty<string>())
        {
            var eqIdx = prop.IndexOf('=');
            // BUG-R40-B12: previously `eqIdx > 0` silently dropped both
            // `--prop =value` (empty key, eqIdx==0) and `--prop key`
            // (no equals, eqIdx==-1). Surface the empty-key form as a
            // hard error so AI callers don't waste a turn wondering why
            // their property had no effect.
            if (eqIdx == 0)
                throw new ArgumentException(
                    $"Invalid --prop '{prop}': key is empty. Use key=value (e.g. --prop name=Title).");
            if (eqIdx > 0)

View on GitHub (pinned to 1ced45e900)

Solutions

1. Use only a documented bare verb as 'command': get, query, set, add, remove, move, swap, view, raw, validate, add-part, raw-set, import.
2. If your 'command' contains spaces, split it: the verb goes in 'command', the target in 'path'/'parent', options in sibling fields and 'props'.
3. Run 'help batch' for the canonical JSON item schema.

Example fix

// before
{"command":"add /slide[1] --type shape --prop text=Hi"}
// after
{"command":"add","parent":"/slide[1]","type":"shape","props":{"text":"Hi"}}

if (!string.IsNullOrEmpty(item.Command) && item.Command.Any(char.IsWhiteSpace))
    throw new InvalidOperationException(
        "'command' must be a bare verb; move the rest into sibling fields. " +
        "e.g. {\"command\":\"add\",\"parent\":\"/slide[1]\",\"type\":\"shape\",\"props\":{...}}");

static bool IsBareVerb(string? c) =>
    !string.IsNullOrEmpty(c) && !c.Any(char.IsWhiteSpace) && ValidBatchCommands.Contains(c);

try { result = Dispatch(item); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Unknown command"))
{ /* ex.Message carries batchHint — surface it to the caller */ }

When it happens

Trigger: A misspelled verb (e.g. 'delete' instead of 'remove', 'insert' instead of 'add'). A whole CLI line placed in 'command' (whitespace detected). A verb from an older/newer version not in this build.

Common situations: An agent trained on the single-command CLI pastes 'add /slide[1] --type shape --prop ...' into the batch command field. A caller uses a synonym the tool never supported.

Related errors

• Batch input must be a JSON array. Got: {rootKind.ToString().
• batch item[{ri}]: unknown field(s) {string.Join(", ", unknow
• Batch item missing required 'command' field. Valid commands:
• Expected "key=value" string in props array
• Unexpected end of JSON

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