larksuite/cli · error

number expects a numeric value, got %s

Error message

number expects a numeric value, got %s

What it means

buildTypedCell enforces the dtype declared for each column in --sheets/--values payloads. A column declared "number" must carry a JSON number (json.Number); any other JSON type (string, bool, object, array, null) triggers this error. The caller adds row/column context and wraps it in a typed validation error.

Source

Thrown at shortcuts/sheets/lark_sheet_table_io.go:692

	if nf != "" {
		cell["cell_styles"] = map[string]interface{}{"number_format": nf}
	}
	if raw == nil {
		return cell, nil
	}
	switch col.Type {
	case "":
		// Type-less column: write the raw JSON scalar as-is so Lark Sheets
		// auto-detects the type (numeric → number, else text). json.Number is
		// kept verbatim for precision; an optional --styles number_format
		// controls display. This is the untyped --values behavior.
		cell["value"] = raw
	case "string":
		cell["value"] = stringifyCellValue(raw)
	case "number":
		n, ok := raw.(json.Number)
		if !ok {
			return nil, fmt.Errorf("number expects a numeric value, got %s", describeJSONType(raw)) //nolint:forbidigo // intermediate error; callers wrap it into a typed --sheets/--values validation error with row/column context
		}
		cell["value"] = n
	case "bool":
		b, ok := raw.(bool)
		if !ok {
			return nil, fmt.Errorf("bool expects true/false, got %s", describeJSONType(raw)) //nolint:forbidigo // intermediate error; callers wrap it into a typed --sheets/--values validation error with row/column context
		}
		cell["value"] = b
	case "date":
		str, ok := raw.(string)
		if !ok {
			return nil, fmt.Errorf("date expects an ISO yyyy-mm-dd string, got %s", describeJSONType(raw)) //nolint:forbidigo // intermediate error; callers wrap it into a typed --sheets/--values validation error with row/column context
		}
		serial, err := isoDateToSerial(str)
		if err != nil {
			return nil, err
		}
		cell["value"] = serial

View on GitHub (pinned to 7fd6ef3c07)

Solutions

  1. Remove quotes from the numeric value so it is a real JSON number: 42 not "42"
  2. Change the column dtype to "string" (or "object") if the values are intentionally text
  3. Replace null/empty numeric cells with a number or restructure to avoid empty cells

Example fix

// before
{"name":"Amount","type":"number","data":["42"]}
// after
{"name":"Amount","type":"number","data":[42]}
Defensive patterns

Strategy: validation

Validate before calling

function assertNumberColumn(col) {
  col.data.forEach((v, i) => {
    if (typeof v !== 'number') throw new Error(`column ${col.name} (number): row ${i} value ${JSON.stringify(v)} is not a JSON number`);
  });
}

Type guard

function isJSONNumber(v) { return typeof v === 'number' && Number.isFinite(v); }

Try / catch

try {
  await run(['lark','sheet','table-put','--sheets',payload]);
} catch (e) {
  if (/number expects a numeric value/.test(e.message)) {
    // de-quote numbers or switch dtype to "string" and retry
  }
  throw e;
}

Prevention

When it happens

Trigger: {"type":"number","name":"Amount"} column with value "42" (quoted string), true, null, or an object; CSV-to-JSON converters quoting all values.

Common situations: Hand-authored JSON quoting numbers by habit; spreadsheet exports that emit everything as strings; null values for empty numeric cells.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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