nanocoai/nanoclaw · error · Error

--group is required

Error message

--group is required

What it means

Thrown by `createTask` when no agent group can be resolved for the new task. The group comes from `groupArg`: for agent callers it is the auto-filled ctx.agentGroupId; for operator/host callers it must be supplied as `--group` (or `--agent_group_id`). Every task series belongs to exactly one agent group, so creation cannot proceed without one.

Source

Thrown at src/cli/resources/tasks.ts:143

}

function selectLiveTasks(mailbox: InboundMailbox, status?: TaskStatus): TaskRow[] {
  return mailbox.listLiveTasks(status);
}

function selectTask(mailbox: InboundMailbox, id: string): TaskRow | undefined {
  return mailbox.getTask(id);
}

function taskId(args: Record<string, unknown>): string {
  const id = str(args.id);
  if (!id) throw new Error('task series id is required');
  return id;
}

async function createTask(args: Record<string, unknown>, ctx: CallerContext) {
  const group = groupArg(args, ctx);
  if (!group) throw new Error('--group is required');
  const prompt = str(args.prompt);
  if (!prompt) throw new Error('--prompt is required');
  const recurrence = normalizeNullableString(args.recurrence) ?? null;
  const script = normalizeNullableString(args.script) ?? null;
  const prepared = prepareScheduledTask({
    name: str(args.name),
    prompt,
    recurrence,
    processAfter: str(args.process_after),
    script,
    dangerouslyOverrideRecurrenceLimit: bool(args.dangerously_override_recurrence_limit),
    timezone: await resolveGroupTimezone(group),
  });
  const { session, row } = await createScheduledTask(group, prepared, {
    originSessionId: ctx.caller === 'agent' ? ctx.sessionId : null,
  });
  return toOutput(session, row);
}

View on GitHub (pinned to 294ef2aee8)

Solutions

1. Add `--group <agent-group-id>` (find it with `ncl groups list`)
2. Alternatively use the accepted alias `--agent_group_id <id>`
3. When automating, resolve the group id once via `ncl groups list --json` and inject it

Example fix

# before
ncl tasks create --prompt "daily report" --name daily
# after
ncl tasks create --group grp_123 --prompt "daily report" --name daily

const groups = await execNclJson(['groups', 'list']);
const group = groups.find(g => g.id === groupId || g.folder === groupId);
if (!group) throw new Error(`unknown agent group ${groupId}`);
await execNcl(['tasks', 'create', '--group', group.id, '--prompt', prompt]);

const hasGroup = (g: unknown): g is string => typeof g === 'string' && g.trim().length > 0;

When it happens

Trigger: An operator runs `ncl tasks create --prompt ...` without `--group`; an agent-runner path where ctx.agentGroupId is somehow unset; passing the group positionally or under a different flag name so both args.group and args.agent_group_id are empty.

Common situations: Operators forgetting --group because the wizard/UI normally fills it in; copying a create command from agent context (where the flag is auto-filled) into host context; referencing a group by folder name instead of its id.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• --status must be pending or paused
• task series id is required
• --prompt is required
• --${column.name.replace(/_/g, '-')} must be true or false
• ${col.name} must be one of: ${col.enum.join(', ')}

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