nanocoai/nanoclaw · error · Error

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.

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

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

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

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

• must be a number, got
• must be one of
• must be true or false, got
• must be valid JSON
• requires a value

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

Appendix: 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)