nanocoai/nanoclaw · error · Error

task series id is required

Error message

task series id is required

What it means

Thrown by `taskId` in the tasks resource when an id-taking task verb (`ncl tasks get|update|cancel|pause|resume|delete|append-log|run --id ...`) is invoked without `--id`. Task operations target an existing task series row keyed by id, so the CLI demands it before doing anything else.

Source

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

    prompt: content.prompt.length > 120 ? content.prompt.slice(0, 117) + '...' : content.prompt,
    has_script: content.script ? 1 : 0,
    origin_session_id: content.originSessionId, // which session created the task (null for CLI-created)
    created_at: row.timestamp,
    tries: row.tries,
  };
}

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),

View on GitHub (pinned to 294ef2aee8)

Solutions

1. Add the flag form: `ncl tasks get --id <task-series-id>`
2. Find the id first via `ncl tasks list` (or `--json` for scripting)
3. In scripts, assert the id variable is non-empty before calling ncl

Example fix

# before
ncl tasks get tsk_abc123
# after
ncl tasks get --id tsk_abc123

if (!taskId || !taskId.startsWith('task-')) {
  throw new Error('task series id is required (see ncl tasks list)');
}
await execNcl(['tasks', 'get', '--id', taskId]);

const isTaskId = (v: unknown): v is string => typeof v === 'string' && v.length > 0;

catch (e) { if (e.message === 'task series id is required') printUsageAndExit(1); else throw e; }

When it happens

Trigger: Running `ncl tasks cancel` or `ncl tasks get` with no --id; passing the id positionally (`ncl tasks get tsk_123`) instead of via the flag; a typo'd flag name so args.id is never set.

Common situations: Assuming positional args work (the ncl grammar is `ncl <resource> <verb> [--id ...]`, not positional); empty $TASK_ID shell variable in automation; id flag named differently in a copied command.

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
• --group 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/1450c5d3baeb67c3. Report an issue: GitHub.