larksuite/cli · error

%s

Error message

%s

What it means

Final rejection for an unrecognized key in a sub-op input: the dispatcher builds a message listing the valid keys and appends a `did you mean` suggestion when the closest known key is near. The raw message is emitted as-is here; the batch dispatcher wraps it into a typed operations validation error.

Source

Thrown at shortcuts/sheets/batch_op_dispatch.go:521

				}
				return fmt.Errorf("%s takes a single \"range\" per sub-op, got %d entries in %q — split them into %d sub-ops (one per range)", sc, len(arr), k, len(arr)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
			}
			if s, isStr := input[k].(string); isStr {
				input["range"] = s
				delete(input, k)
				continue
			}
		}
		msg := fmt.Sprintf("unknown input key %q", k)
		display := make([]string, 0, len(vocab))
		for name := range vocab {
			display = append(display, strings.ReplaceAll(name, "-", "_"))
		}
		sort.Strings(display)
		if match := suggest.Closest(strings.ToLower(hv), display, 1); len(match) > 0 {
			msg += fmt.Sprintf(" — did you mean %q?", match[0])
		}
		return fmt.Errorf("%s", msg) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
	}
	return nil
}

// translateBatchOp 把一个 CLI 视角的 {shortcut, input} 翻成底层 MCP
// batch_update 的 {tool_name, input}。`index` 用于错误信息定位。input 用
// shortcut 的 CLI flag 名（连字符/下划线均可），经该 shortcut 的 standalone
// translator 翻成 MCP body。
//
// 失败场景：
//   - shortcut 字段缺失 / 非 string
//   - shortcut 不在 dispatch 表（拼写错；read 操作；嵌套 fan-out wrapper）
//   - input 不是 object
//   - input 里手填了 operation（由 shortcut 名隐含，禁手填以防 mismatch）
//   - input 顶层出现 cell_styles / cell_merges / styles（误贴 MCP body 包裹结构）
//   - 子操作的 translator 报错（如缺必填字段）
func translateBatchOp(raw interface{}, token string, index int) (map[string]interface{}, error) {
	return translateBatchOpWithDispatch(raw, token, index, batchOpDispatch, "+batch-update")

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Apply the `did you mean` suggestion from the message (e.g. rename `valeus` to `values`).
2. Run `lark-cli schema` for the shortcut to list the exact accepted fields for the op.
3. Remove fields the target op does not support, or move them to a sub-op that accepts them.

Example fix

// before
{"op": "set", "range": "A1:B2", "valeus": [["x"]]}
// error: did you mean "values"?
// after
{"op": "set", "range": "A1:B2", "values": [["x"]]}

var validKeys = map[string]bool{"op": true, "range": true, "values": true, "cell_range": true}
for k := range subOp {
    if !validKeys[strings.ReplaceAll(k, "-", "_")] {
        return fmt.Errorf("unknown key %q", k)
    }
}

When it happens

Trigger: A sub-op input contains a key that is not in the op's vocabulary under any accepted spelling — a typo like `valeus` instead of `values`, a field the op does not support, or a key with an unsupported naming convention.

Common situations: Typos in hand-written payloads; using fields from one op type in another op that lacks them; stale payloads after a vocabulary change; guessing flag names instead of checking `schema`.

Related errors

• Range needs a maximum column: {range_ref}
• Range needs a maximum row: {range_ref}
• %s contains unknown field %q
• %s got conflicting values for %q under two spellings (%q and
• %s got both %q and %q — keep %q and drop the other

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/d054f27e0fbe62e1. Report an issue: GitHub.