nanocoai/nanoclaw · error · Error

--status must be pending or paused

Error message

--status must be pending or paused

What it means

Thrown by `statusFilter` in the tasks resource when `ncl tasks list --status <value>` is given anything other than `pending` or `paused`. Those are the only two statuses that make sense to filter a listing by (active/dormant states); terminal or runtime states like `running`, `done`, or `cancelled` are not accepted list filters.

Source

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

function bool(value: unknown): boolean {
  return value === true || value === 'true' || value === '1';
}

function normalizeNullableString(value: unknown): string | null | undefined {
  if (value === undefined) return undefined;
  if (value === null) return null;
  if (typeof value !== 'string') return String(value);
  const trimmed = value.trim();
  if (trimmed === '' || trimmed === 'null' || trimmed === 'none') return null;
  return value;
}

function statusFilter(args: Record<string, unknown>): TaskStatus | undefined {
  const status = str(args.status);
  if (!status) return undefined;
  if (status !== 'pending' && status !== 'paused') {
    throw new Error('--status must be pending or paused');
  }
  return status;
}

function groupArg(args: Record<string, unknown>, ctx: CallerContext): string | undefined {
  if (ctx.caller === 'agent') return ctx.agentGroupId;
  return str(args.group) ?? str(args.agent_group_id);
}

async function ownSession(sessionId: string, ctx: CallerContext): Promise<ScopedSession> {
  const session = await getSession(sessionId);
  if (!session) throw new Error(`session not found: ${sessionId}`);
  if (ctx.caller === 'agent' && session.agent_group_id !== ctx.agentGroupId) {
    throw new Error(`session not found: ${sessionId}`);
  }
  return { id: session.id, agent_group_id: session.agent_group_id };
}

View on GitHub (pinned to 294ef2aee8)

Solutions

1. Use `--status pending` or `--status paused` — the only accepted filters
2. Omit --status entirely to list tasks regardless of status, then filter client-side or via --json
3. Check `ncl tasks help` for the current flag contract

Example fix

# before
ncl tasks list --status running
# after
ncl tasks list --status pending

const TASK_LIST_STATUSES = ['pending', 'paused'] as const;
const s = status satisfies string | undefined;
if (s && !TASK_LIST_STATUSES.includes(s as any)) {
  throw new Error(`--status must be one of ${TASK_LIST_STATUSES.join('|')}`);
}

const isListFilterableStatus = (s: unknown): s is 'pending' | 'paused' =>
  s === 'pending' || s === 'paused';

When it happens

Trigger: Running `ncl tasks list --status running`, `--status done`, `--status active`, or any arbitrary string. The filter runs early in the list handler, before any DB query.

Common situations: Assuming the filter accepts the full task status enum (create/cancel/update use more statuses than list accepts); copying a status from `ncl tasks get` output into a list filter; scripts written against an older or assumed API surface.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• task series id is required
• --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/b0f80fda898cbc9e. Report an issue: GitHub.