nanocoai/nanoclaw · error

invalid-args

invalid-args

Error message

${errMsg(e)}

What it means

The command's argument parser (`cmd.parseArgs`) threw while validating the request args — a required flag missing, an unknown flag, or a value of the wrong type/shape. The thrown message is returned verbatim with code `invalid-args`, so the exact parse problem is in the message.

Source

Thrown at src/cli/dispatch.ts:172

      .join(' ');

    await requestApproval({
      session,
      agentName,
      action: 'cli_command',
      payload: { frame: { id: req.id, command: req.command, args: req.args }, callerContext: ctx },
      title: `CLI: ${req.command}`,
      question: `Agent "${agentName}" wants to run:\n\`ncl ${req.command}${argSummary ? ' ' + argSummary : ''}\``,
    });

    return err(req.id, 'approval-pending', 'Approval request sent to admin. You will be notified of the result.');
  }

  let parsed: unknown;
  try {
    parsed = cmd.parseArgs(req.args);
  } catch (e) {
    return err(req.id, 'invalid-args', errMsg(e));
  }

  try {
    let data = await cmd.handler(parsed, ctx);

    // Post-handler group-scope enforcement. Applies only to the auto-generated
    // `list` / `get` handlers (`cmd.generic`), which return raw DB rows carrying
    // the resource's `scopeField`:
    //   - `list` → drop rows that don't belong to the caller's agent group
    //              (covers `groups list`, where the generic list handler ignores
    //              the auto-filled `--id`)
    //   - `get`  → reject if the single row belongs to another group
    // Custom operations return ad-hoc shapes (e.g. `groups config get` → a config
    // object with no `id`) and are NOT checked here — they would be falsely
    // rejected, and they're already pinned to the caller's group by the
    // pre-handler `--id` auto-fill (groups/destinations) or gated behind approval,
    // so they can't reach another group's data anyway.
    if (ctx.caller === 'agent' && cmd.resource && cmd.generic) {

View on GitHub (pinned to 294ef2aee8)

Solutions

1. Read the message — it names the offending flag/type
2. Run `ncl <resource> <verb> help` to see the exact accepted flags for this build
3. Fix quoting (quote values with spaces; avoid shell-splitting JSON) and re-run
4. If flags changed, update scripts/agent instructions to the current help output

Example fix

// before
ncl wirings create --messaging-group
// after
ncl wirings create --messaging-group <mg-id> --agent-group <ag-id>

const help = await runNcl(`${resource} ${verb} help`);
// build args strictly from the flags listed in help; drop unknown keys
const args = pick(knownFlagsOnly(rawArgs, help));

function hasRequiredFlags(args: Record<string, unknown>, required: string[]): boolean {
  return required.every(k => args[k] !== undefined && args[k] !== null && args[k] !== '');
}

On code === 'invalid-args', parse the returned message to identify the flag, correct, and re-run once; surface the message verbatim to the operator if it persists.

When it happens

Trigger: `ncl wirings create` without required flags; passing a non-UUID where an id is expected; booleans given as strings in unexpected positions; JSON args with wrong field types from an agent-built command line.

Common situations: Agent constructs ncl argv from chat text and drops or mangles flags; shell quoting eating a value; using flags from an older version's syntax after a resource definition changed.

Related errors

• messaging group not found: ${id}
• --${column.name.replace(/_/g, '-')} must be true or false
• ${col.name} must be one of: ${col.enum.join(', ')}
• Nothing to update — provide at least one of: --provider, --m
• --name is required

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