nanocoai/nanoclaw · error · Error

${flag} is required

Error message

${flag} is required

What it means

During strict validation of a custom verb, a ColumnDef marked `required: true` was absent from the parsed args (value undefined and no default). The verb cannot proceed without it, so validation fails before the handler runs.

Source

Thrown at src/cli/crud.ts:413

  defs: ColumnDef[],
  args: Record<string, unknown>,
  opts: { allowExtra?: readonly string[] } = {},
): Record<string, unknown> {
  const declared = new Map(defs.map((d) => [d.name, d]));
  const allowed = new Set<string>([...declared.keys(), ...(opts.allowExtra ?? DISPATCH_INJECTED_KEYS)]);

  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}"`);

View on GitHub (pinned to 294ef2aee8)

Solutions

  1. Read the usage block in the error message — it lists required flags with `<...>` markers
  2. Re-run with the required flag: add `--<name> <value>`
  3. For custom-operation authors: give the ColumnDef a `default` if the flag should be optional

Example fix

# before
ncl wirings create --agent-group-id g1
# Error: --messaging-group-id is required

# after
ncl wirings create --agent-group-id g1 --messaging-group-id m1
Defensive patterns

Strategy: validation

Validate before calling

const missing = defs.filter((d) => d.required && args[d.name] === undefined);
if (missing.length) throw new Error(`missing required: ${missing.map((d) => '--' + d.name).join(' ')}`);

Try / catch

catch (e) { if (e instanceof Error && /is required$/.test(e.message)) { /* collect and prompt */ } else throw e; }

Prevention

When it happens

Trigger: Omitting a required flag entirely, e.g. `ncl messaging-groups create` when `--name` is required; passing the flag with a different spelling so it lands as an unknown key (which first triggers the unknown-flag error); passing `--flag` value-less so it parses as boolean true rather than the expected typed value (that hits the requires-a-value error instead).

Common situations: Minimal invocations copied from docs that omit a newly-required flag after a version bump; agents truncating long commands; conditional shell logic that skips a flag.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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