nanocoai/nanoclaw · error · Error

${flag} must be true or false, got "${v}"

Error message

${flag} must be true or false, got "${v}"

What it means

A flag declared with `type: 'boolean'` only accepts true/false in the forms `true|false`, `1|0`, or the bare-boolean values. Any other string fails with the received value echoed.

Source

Thrown at src/cli/crud.ts:431

      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;
      }
      case 'string':
        out[def.name] = String(v);
        break;
    }
    if (def.enum && !def.enum.includes(String(out[def.name]))) {
      throw new Error(`${flag} must be one of: ${def.enum.join(', ')}`);

View on GitHub (pinned to 294ef2aee8)

Solutions

  1. Use exactly `true` or `false` (lowercase), or `1`/`0`
  2. For a bare toggle, pass just `--flag` with no value (parsed as boolean true)
  3. Check the usage block for the accepted forms

Example fix

# before
ncl groups restart --id g1 --rebuild yes
# Error: --rebuild must be true or false, got "yes"

# after
ncl groups restart --id g1 --rebuild
Defensive patterns

Strategy: validation

Validate before calling

const ok = v === true || v === false || ['true','false','1','0'].includes(String(v).toLowerCase());
if (!ok) throw new Error('boolean flag must be true/false/1/0');

Type guard

function isBooleanFlagValue(v: unknown): v is boolean | 'true' | 'false' | '1' | '0' {
  return v === true || v === false || ['true','false','1','0'].includes(v as string);
}

Try / catch

catch (e) { if (e instanceof Error && /must be true or false/.test(e.message)) { /* map yes/no → true/false */ } else throw e; }

Prevention

When it happens

Trigger: `--rebuild yes`, `--engage true-ish`, `--flag on/off`, `--flag True` (capitalized — not matched by the strict string comparison), or an arbitrary word parsed as the flag's value.

Common situations: Using YAML-ish `yes/no` or `on/off` conventions from other CLIs; capitalized booleans; agents writing natural-language truthiness.

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

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