nanocoai/nanoclaw · error · Error

${flag} requires a value

Error message

${flag} requires a value

What it means

The ncl client parses a value-less `--flag` as boolean `true`. When strict validation sees `true` for a flag whose declared type is not boolean (number, string, json), it throws `<flag> requires a value` — the caller wrote `--flag` but no value after it.

Source

Thrown at src/cli/crud.ts:419

  for (const key of Object.keys(args)) {
    if (!allowed.has(key)) {
      throw new Error(`unknown flag --${key.replace(/_/g, '-')}`);
    }
  }

  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);

View on GitHub (pinned to 294ef2aee8)

Solutions

1. Supply an explicit value: `--flag value` or `--flag=value`
2. For values starting with a dash, use the `=` form (`--count=-5`)
3. Quote multi-word values: `--message "hello there"`

Example fix

# before
ncl groups restart --id g1 --message
# Error: --message requires a value

# after
ncl groups restart --id g1 --message "respawn now"

for (const [k, v] of Object.entries(args)) {
  if (v === true && !booleanFlags.has(k)) throw new Error(`--${k} needs an explicit value`);
}

catch (e) { if (e instanceof Error && /requires a value$/.test(e.message)) { /* re-prompt for the value */ } else throw e; }

When it happens

Trigger: `ncl tasks create --title` (nothing after --title, so the next token is consumed or the flag is bare); `--rebuild --id g1` style ordering where a value-less flag precedes another flag; a value that starts with `--` being parsed as a flag rather than a value.

Common situations: Truncated terminal commands; agents generating flag lists and forgetting value pairs; a value legitimately starting with a dash (e.g. negative number) needing `--flag=-5` syntax.

Related errors

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

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