coleam00/Archon · error · Error

Invalid --status '${opts.status}'. Valid: ${workflowRunStatu

Error message

Invalid --status '${opts.status}'. Valid: ${workflowRunStatusSchema.options.join(', ')}.

What it means

`archon workflow runs --status` validates its value against workflowRunStatusSchema before querying. An unrecognized status string is rejected with the list of valid schema options, and --json mode emits {ok:false} instead of throwing.

Source

Thrown at packages/cli/src/commands/workflow.ts:3955

      console.log(
        `  ${run.id.slice(0, 8)}  ${run.workflow_name}  (${formatAge(run.started_at)})  adopt: workflow run <name> --adopt ${run.id}`
      );
    }
    console.log('');
    return;
  }

  let statusFilter: WorkflowRunStatus | undefined;
  if (opts.status) {
    const parsed = workflowRunStatusSchema.safeParse(opts.status);
    if (!parsed.success) {
      const msg = `Invalid --status '${opts.status}'. Valid: ${workflowRunStatusSchema.options.join(', ')}.`;
      // --json never throws — emit one parseable {ok:false} line (write-command contract).
      if (opts.json) {
        await writeJsonLine({ ok: false, error: msg });
        return;
      }
      throw new Error(msg);
    }
    statusFilter = parsed.data;
  }

  // Scope to this project by exact registration first, then through the
  // checkout's canonical repository path. This preserves an explicitly
  // registered linked worktree while allowing another linked worktree to share
  // its registered primary checkout. Ordinary clones remain unchanged (#2613).
  // --all opts out of scoping. A lookup failure or an unregistered cwd both
  // fall back to the global list — never a silent wrong-scope (the human path
  // prints an explicit note below).
  let codebase = null;
  if (!opts.all) {
    try {
      codebase = await findCodebaseForCheckoutPath(cwd);
    } catch (error) {
      getLog().warn({ err: error as Error, cwd }, 'cli.workflow_runs_codebase_lookup_failed');
    }

View on GitHub (pinned to 0773b97458)

Solutions

Use a status listed in the error message verbatim (they come from workflowRunStatusSchema.options).
Run `archon workflow runs --status <valid>` after checking the schema/docs for current enum values.
In scripts, validate the status against the schema options (or a copied constant) before invoking the CLI.

Example fix

// before
archon workflow runs --status success
// after
archon workflow runs --status completed

Defensive patterns

Strategy: validation

Validate before calling

const VALID=['pending','running','failed','completed','cancelled','awaiting_gate','waiting']; if (!VALID.includes(status)) throw new Error(`bad --status ${status}; use one of ${VALID.join(',')}`);

Type guard

type RunStatus = typeof workflowRunStatusSchema.options[number]; function isRunStatus(s: string): s is RunStatus { return (workflowRunStatusSchema.options as readonly string[]).includes(s); }

Try / catch

try { await runs({ status }); } catch (e) { if (String(e.message).startsWith('Invalid --status')) { console.error(e.message); process.exit(2); } throw e; }

Prevention

Import workflowRunStatusSchema (or its derived union type) instead of hardcoding status strings.
Derive allowed statuses from the schema options at call time so version changes surface at compile time.
Capture valid values from the error message itself, which enumerates schema options.

When it happens

Trigger: `archon workflow runs --status typo` where the value is not one of workflowRunStatusSchema.options (e.g. 'fail', 'success', 'complete' instead of the schema's enum values).

Common situations: Hand-written shell scripts with hardcoded status names, status names changed between Archon versions, or copying status names from a different tool.

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

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/53470ee1708d2026. Report an issue: GitHub.