nanocoai/nanoclaw · error · Error

${flag} must be a number, got "${v}"

Error message

${flag} must be a number, got "${v}"

What it means

A flag declared with `type: 'number'` received a value that `Number()` coerces to NaN. Validation throws before the handler runs, echoing the offending value.

Source

Thrown at src/cli/crud.ts:424

  }

  const out: Record<string, unknown> = { ...args };
  for (const def of defs) {
    const flag = `--${def.name.replace(/_/g, '-')}`;
    const v = args[def.name];
    if (v === undefined) {
      if (def.required) throw new Error(`${flag} is required`);
      if (def.default !== undefined) out[def.name] = def.default;
      continue;
    }
    // The client parses a value-less `--flag` as boolean true.
    if (v === true && def.type !== 'boolean') {
      throw new Error(`${flag} requires a value`);
    }
    switch (def.type) {
      case 'number': {
        const n = Number(v);
        if (Number.isNaN(n)) throw new Error(`${flag} must be a number, got "${v}"`);
        out[def.name] = n;
        break;
      }
      case 'boolean': {
        if (v === true || v === 'true' || v === '1') out[def.name] = true;
        else if (v === false || v === 'false' || v === '0') out[def.name] = false;
        else throw new Error(`${flag} must be true or false, got "${v}"`);
        break;
      }
      case 'json': {
        if (typeof v === 'string') {
          try {
            out[def.name] = JSON.parse(v);
          } catch (err) {
            throw new Error(`${flag} must be valid JSON`, { cause: err });
          }
        }
        break;

View on GitHub (pinned to 294ef2aee8)

Solutions

1. Pass a bare numeric literal: `--count 10`
2. Strip units/suffixes from the value
3. For unit-bearing quantities, check the verb help for the expected unit and convert first (e.g. `10s` → `--timeout 10000` if ms)

Example fix

# before
ncl tasks create --interval 30s ...
# Error: --interval must be a number, got "30s"

# after
ncl tasks create --interval 30 ...

if (typeof v === 'string' && Number.isNaN(Number(v))) throw new Error(`value for number flag is not numeric: ${v}`);

function isNumericFlagValue(v: unknown): v is number | string {
  return typeof v === 'number' || (typeof v === 'string' && !Number.isNaN(Number(v)) && v.trim() !== '');
}

catch (e) { if (e instanceof Error && /must be a number/.test(e.message)) { /* coerce or re-ask */ } else throw e; }

When it happens

Trigger: Passing non-numeric text to a number flag: `--priority high`, `--count 10px`; passing an empty string; passing a boolean-adjacent token like `--count true`; passing a number with thousands separator or unit (`--timeout 10s`).

Common situations: Copy-pasting values from prose or docs; locale-formatted numbers (`1,5`); units accidentally included; agents guessing value formats.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• ${flag} must be true or false, got "${v}"
• unknown flag --${key.replace(/_/g, '-')}
• ${flag} is required
• ${flag} requires a value
• ${flag} must be valid JSON

AI-assisted analysis of nanocoai/nanoclaw@294ef2aee8 (2026-08-28). Data as JSON: /api/errors/e0c1ba322e342e9b. Report an issue: GitHub.