nanocoai/nanoclaw · error · Error

unknown flag --${key.replace(/_/g, '-')}

Error message

unknown flag --${key.replace(/_/g, '-')}

What it means

validateArgs runs in strict mode for custom verbs that declare `args` (a ColumnDef list). After hyphens are normalized to underscores, every key in the parsed args must be either a declared flag or one of the dispatcher-injected keys (`id`, `agent_group_id`, `group`). Any other key is rejected as `unknown flag --<key>` so typos surface immediately instead of being silently ignored.

Source

Thrown at src/cli/crud.ts:404

/**
 * Validate `args` (already underscore-normalized) against a ColumnDef list:
 * unknown-flag rejection, required, enum, and type coercion per the declared
 * type. Returns a coerced copy; throws with a focused message on the first
 * problem. Works from any ColumnDef list so generic CRUD resources can opt
 * into the same strictness later without a second validator.
 */
export function validateArgs(
  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': {

View on GitHub (pinned to 294ef2aee8)

Solutions

1. Run `ncl <resource> help` or read the usage block appended to the error to see the exact accepted flags
2. Fix the misspelling or remove the extraneous flag
3. If writing a custom operation, declare the flag in the verb's `args: ColumnDef[]` list

Example fix

# before
ncl groups restart --id g1 --rebild
# Error: unknown flag --rebild

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

const allowed = new Set([...declaredFlagNames, 'id', 'agent_group_id', 'group']);
const extra = Object.keys(args).filter((k) => !allowed.has(k));
if (extra.length) throw new Error(`not accepted: ${extra.join(', ')}`);

function hasOnlyAllowedKeys(args: Record<string, unknown>, allowed: readonly string[]): boolean {
  return Object.keys(args).every((k) => allowed.includes(k));
}

catch (e) { if (e instanceof Error && e.message.startsWith('unknown flag')) { /* surface allowed list from help */ } else throw e; }

When it happens

Trigger: Passing a flag a custom verb doesn't declare, e.g. `ncl tasks create --priority high` when the verb's args omit `priority`; misspelling a declared flag (`--mesage`); passing flags belonging to a different verb; or a verb that declares no `args` receiving any flag at all is fine, but one WITH declared args rejects everything undeclared.

Common situations: Assuming a generic verb accepts the same flags as another resource's verb; version drift where a flag was renamed or removed upstream; agents guessing flag names without reading the usage block.

Related errors

• ${flag} is required
• ${flag} requires a value
• ${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/e81f9e95427a9e73. Report an issue: GitHub.