iOfficeAI/OfficeCLI · error · ArgumentException

Invalid --prop '{prop}': key is empty. Use key=value (e.g. -

Error message

Invalid --prop '{prop}': key is empty. Use key=value (e.g. --prop name=Title).

What it means

Thrown by ParsePropsArray when a --prop token has an '=' at index 0, i.e. the key is empty (e.g. '--prop =value'). Previously this was silently dropped (BUG-R40-B12), so AI callers wasted turns wondering why their property had no effect; it is now a hard error. The check fires only on the CLI --prop path, not the batch props dict.

Source

Thrown at src/officecli/CommandBuilder.cs:1274

                      + "\"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)
            {
                var key = prop[..eqIdx];
                var value = prop[(eqIdx + 1)..];
                // CONSISTENCY(text-escape-boundary): C-style escape resolution
                // (\\n, \\t, \\r, \\\\) is a CLI-input concern only. The shell
                // gives us the literal four-character sequence `\\n` which a
                // user typing `--prop text='line1\\nline2'` plainly wants as
                // a newline. Handlers no longer call TextEscape.Resolve
                // internally — that double-resolution mangled batch JSON
                // payloads, where `"text": "hello\\nworld"` already arrives
                // as `hello\\nworld` literal after JSON parsing and must NOT
                // be turned into a newline. Affected keys are the text-valued
                // props: `text`, `value`, and the row-level `c1…cN` cell-text
                // shortcuts (so `--prop c1='a\nb'` breaks the line exactly like
                // `--prop text=` does); other props (colors, paths, numbers)
                // are passed through untouched.

View on GitHub (pinned to 1ced45e900)

Solutions

Use the form '--prop key=value' with a non-empty key, e.g. --prop text=Hi.
Check any shell variable expansion that produced the key side — ensure it is set and non-empty.
For batch JSON, pass props as an object {"key":"value"} instead of --prop tokens.

Example fix

# before
officecli set --path /Sheet1/A1 --prop =value
# after
officecli set --path /Sheet1/A1 --prop value=hello

Defensive patterns

Strategy: validation

Validate before calling

// CLI --prop tokens: reject empty key before dispatch
foreach (var p in props ?? Array.Empty<string>())
{
    var eq = p.IndexOf('=');
    if (eq == 0)
        throw new ArgumentException($"Invalid --prop '{p}': empty key. Use key=value.");
    if (eq < 0)
        throw new ArgumentException($"Invalid --prop '{p}': no '='. Use key=value.");
}

Type guard

static bool IsValidPropToken(string p)
{
    var eq = p.IndexOf('=');
    return eq > 0;
}

Try / catch

try { dict = ParsePropsArray(props); }
catch (ArgumentException ex) when (ex.Message.Contains("Invalid --prop"))
{ /* report which token is malformed and ask for key=value */ }

Prevention

Always emit --prop as 'key=value' with a non-empty key.
Check shell variable expansion that builds the key side.
Prefer the batch JSON props object over --prop tokens to avoid shell escaping.

When it happens

Trigger: Calling 'officecli <cmd> --prop =value'. A shell expansion that left the key empty (e.g. an unset variable before '='). A typo like '--prop =text=Hi'.

Common situations: A script builds --prop arguments and a variable for the key is unset, producing '--prop =value'. A user types the prop in the wrong order.

Related errors

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