larksuite/cli · error

--%s must be a number, got %s

Error message

--%s must be a number, got %s

What it means

Raw-type validation error from validateRawTypes in the sheets batch flag view: a flag whose target Go type is `int` received a JSON value that is not a number (e.g. string, bool, object). This preserves batch/standalone parity with cobra's parse-time rejection. The intermediate error is wrapped into a typed operations validation error by the batch dispatcher.

Source

Thrown at shortcuts/sheets/flag_view.go:304

	for rawKey, val := range m.raw {
		name := rawKey
		typ, ok := declaredType[name]
		if !ok {
			// flag-defs use hyphen names; tolerate the underscore form users send.
			name = strings.ReplaceAll(rawKey, "_", "-")
			typ, ok = declaredType[name]
		}
		if !ok {
			continue // unknown key — leave it for the translator / schema layer
		}
		switch typ {
		case "int":
			// Int(): float64 → int(t) truncates, so a non-integer number would
			// be silently floored (1.9 → 1). Standalone cobra rejects it at
			// parse time; reject here too to keep batch/standalone parity.
			f, isNum := val.(float64)
			if !isNum {
				return fmt.Errorf("--%s must be a number, got %s", name, jsonTypeName(val)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
			}
			if math.Trunc(f) != f {
				return fmt.Errorf("--%s must be an integer, got %s", name, strconv.FormatFloat(f, 'g', -1, 64)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
			}
		case "float64":
			if _, isNum := val.(float64); !isNum {
				return fmt.Errorf("--%s must be a number, got %s", name, jsonTypeName(val)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
			}
		case "bool":
			if _, isBool := val.(bool); !isBool {
				return fmt.Errorf("--%s must be a boolean, got %s", name, jsonTypeName(val)) //nolint:forbidigo // intermediate error; the batch dispatcher wraps it into a typed operations validation error
			}
		}
	}
	return nil
}

// normalizeAndValidateEnums applies the same flat string-enum contract as the

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Remove quotes so the value is a JSON number: 5 instead of "5".
2. Check the expected type via --print-schema or --help for the flag.
3. Coerce upstream values to numbers before building the JSON payload.

Example fix

// before
--row '{"row_id": "12"}'  // string
// after
--row '{"row_id": 12}'    // number

function assertIntLike(obj, key) {
  const v = obj[key];
  if (typeof v !== "number" || !Number.isInteger(v)) {
    throw new Error(`${key} must be a JSON number, got ${typeof v}`);
  }
}

function isJsonNumber(v: unknown): v is number {
  return typeof v === "number" && Number.isFinite(v);
}

try {
  runCommand(args);
} catch (e) {
  if (/must be a number, got/.test(e.message)) {
    // inspect jsonTypeName in the message and unquote/fix the JSON value
  }
}

When it happens

Trigger: Passing `--flag '{"x": "5"}'` or a quoted number / boolean / nested value for a field declared int; JSON-decoded value arrives as something other than float64.

Common situations: Quoting numbers inside JSON payloads; environment/config substitution injecting strings; copy-pasting payloads where an id was a string in another API.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• --%s must be an integer, got %s
• +csv-get truncated the requested range at {source_range}; na
• Multiple sheets matched; pass --sheet-id or --sheet-name
• %svalue %v is below minimum %v
• %svalue %v is above maximum %v

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