Run ${run.id}'s gate does not declare decision '${decision}'

Error message

Run ${run.id}'s gate does not declare decision '${decision}'. Declared decisions: ${declaredIds.join(', ')}.

What it means

The gate does declare a custom decisions vocabulary, but the submitted decision id is not among the declared ids. assertRespondable checks the submitted decision against approval.decisions and rejects anything not listed.

Source

Thrown at packages/core/src/operations/workflow-operations.ts:909

 * pair (#2707 step 2).
 */
export function assertRespondable(run: WorkflowRun, decision: string): ApprovalContext {
  const approval = assertApprovable(run);
  if (approval.type !== 'approval' && approval.type !== undefined) {
    throw new Error(
      `Run ${run.id}'s gate ('${approval.type}') only accepts 'approve' or 'reject' — ` +
        `'${decision}' is not a valid response here.`
    );
  }
  if (approval.decisionsAuthored !== true) {
    throw new Error(
      `Run ${run.id}'s gate only accepts 'approve' or 'reject' — '${decision}' is not one of its ` +
        'declared decisions. Declare `approval.decisions:` on the gate node to author a broader vocabulary.'
    );
  }
  const declaredIds = (approval.decisions ?? []).map(d => d.id);
  if (!declaredIds.includes(decision)) {
    throw new Error(
      `Run ${run.id}'s gate does not declare decision '${decision}'. Declared decisions: ` +
        `${declaredIds.join(', ')}.`
    );
  }
  return approval;
}

/**
 * Resolve a paused gate with an author-declared decision beyond approve/reject
 * (#2707 step 2 — the general `workflow respond <id> <decision> [text]` verb).
 * `approve`/`reject` are NOT handled here — `respondToWorkflow` delegates those
 * to the existing `approveWorkflow`/`rejectWorkflow` functions unchanged, so
 * every gate shape that existed before this PR keeps its exact prior behavior
 * (legacy `on_reject` rework/cancel, `capture_response`, interactive_loop,
 * writeback). This function only ever resolves a new-mode plain gate node
 * (`decisionsAuthored: true`) immediately with structured `{decision, text}`
 * output — the same shape `approveWorkflow`'s new-mode branch writes, just
 * with a caller-supplied `decision` instead of the literal `'approve'`.

View on GitHub (pinned to 0773b97458)

Solutions

Read the run's declared decisions (the error lists them) and send one of those exact ids.
Fix typos/casing/whitespace in the decision id at the caller.
If a new decision is genuinely needed, add it to `approval.decisions:` in the workflow for future runs (already-running runs keep their declared set).

Example fix

// before
await respondToWorkflow(runId, 'Request_Changes');
// after
const declared = ['approve', 'reject', 'request_changes'];
await respondToWorkflow(runId, 'request_changes'); // exact declared id

Defensive patterns

Strategy: validation

Validate before calling

const declaredIds = (gate.decisions ?? []).map(d => d.id);
if (!declaredIds.includes(decision)) {
  throw new Error(`'${decision}' not declared. Declared: ${declaredIds.join(', ')}`);
}

Type guard

function isDeclaredDecision(decision, gate) {
  return (gate.decisions ?? []).some(d => d.id === decision);
}

Try / catch

try {
  await respondToWorkflow(runId, decision);
} catch (e) {
  const m = e.message.match(/Declared decisions: (.+)\./);
  if (m) console.error(`Use one of: ${m[1]}`);
  throw e;
}

Prevention

Load declared decisions from the run API instead of hardcoding ids in handlers.
Avoid renaming decision ids while runs are in flight; add new ids instead.
Trim and lowercase-normalize decision ids at the UI boundary before sending.

When it happens

Trigger: Calling respondToWorkflow / workflowRespondCommand / the respond API route with a decision string that is not in the gate node's `approval.decisions:` id list — e.g. typo 'approve ' (trailing space), 'Accept', or an id renamed in the workflow after the run started.

Common situations: Workflow decisions renamed between authoring and running, so in-flight runs declare old ids; case or whitespace mismatch in decision ids; platform handlers forwarding button values that don't match declared ids.

Related errors

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