What causes "Failed to pause workflow run: ${err.message}" in coleam00/Archon?

Read the inner err.message: if it is a serialization error, fix the approvalContext passed to pauseWorkflowRun (plain JSON-safe object only)

coleam00/Archon · error

Failed to pause workflow run: ${err.message}

Error message

Failed to pause workflow run: ${err.message}

What it means

This is the wrap-around error for unexpected database failures while pausing a workflow run. The pause function re-throws the intentional 'Workflow run not found or not in running state' error unchanged, but any other error (connection loss, SQL failure, serialization error) is logged as db.workflow_run_pause_failed and re-thrown as 'Failed to pause workflow run: <inner message>'.

Source

Thrown at packages/core/src/db/workflows.ts:1433

        id,
        // Caller-supplied run-level metadata (e.g. `pending_writeback`) rides the SAME
        // atomic write so there is no window where the run is paused without it (M3).
        JSON.stringify(extraMetadata ?? {}),
        // The complete gate context. JSON.stringify drops undefined, and the write
        // replaces rather than merges, so an optional field the caller left unset is
        // simply absent — no explicit-null reset list to keep in sync.
        JSON.stringify(approvalContext),
      ]
    );
    if (result.rowCount === 0) {
      getLog().warn({ workflowRunId: id }, 'db.workflow_run_pause_no_match');
      throw new Error(`Workflow run not found or not in running state (id: ${id})`);
    }
  } catch (error) {
    if (error instanceof Error && error.message.startsWith('Workflow run not found')) throw error;
    const err = error as Error;
    getLog().error({ err, workflowRunId: id }, 'db.workflow_run_pause_failed');
    throw new Error(`Failed to pause workflow run: ${err.message}`);
  }
}

/** Pause a running run on a persisted time/event condition. */
export async function pauseWorkflowRunForWait(
  id: string,
  waitContext: WorkflowWaitContext,
  pause: WorkflowWaitPause
): Promise<void> {
  const parsedWaitContext = workflowWaitContextSchema.parse(waitContext);
  try {
    await getDatabase().withTransaction(async query => {
      const result = await query(
        `UPDATE remote_agent_workflow_runs
         SET status = 'paused', metadata = ${replaceWaitMetadata(2)}
         WHERE id = $1 AND status = 'running'`,
        [id, JSON.stringify(parsedWaitContext)]
      );

View on GitHub (pinned to 0773b97458)

Solutions

Read the inner err.message: if it is a serialization error, fix the approvalContext passed to pauseWorkflowRun (plain JSON-safe object only)
Check DB connectivity/pool health and retry the pause with backoff for transient errors
Verify the database schema is current (additive migrations applied) for remote_agent_workflow_runs
Confirm the run is still in 'running' state to rule out a concurrent status change causing a locked-row conflict

Example fix

// before
await pauseWorkflowRun(id, { req, callback }); // callback makes it non-JSON-safe
// after
await pauseWorkflowRun(id, JSON.parse(JSON.stringify({ reqId: req.id })));

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure approvalContext is JSON-serializable before calling
JSON.stringify(approvalContext); // throws early on circular refs / BigInt
const run = await getWorkflowRun(id);
if (run?.status !== 'running') throw new Error(`run ${id} not pausable (status=${run?.status})`);

Type guard

function isPauseFailure(e: unknown): e is Error {
  return e instanceof Error && e.message.startsWith('Failed to pause workflow run:');
}

Try / catch

try {
  await pauseWorkflowRun(id, ctx);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Workflow run not found')) throw e;
  // DB-level failure: inspect inner message, retry transient errors
  if (/ECONNREFUSED|ETIMEDOUT|deadlock|serialization/i.test(e.message)) {
    await retryWithBackoff(() => pauseWorkflowRun(id, ctx));
    return;
  }
  throw e;
}

Prevention

Pass only plain JSON-safe objects as approvalContext
Apply all schema migrations so remote_agent_workflow_runs matches the binary's expectations
Distinguish the intentional 'not found' error from DB failures exactly as the function does
Monitor pool health; pause failures spike under pool exhaustion

When it happens

Trigger: pauseWorkflowRun(id, approvalContext) throws a non-'not found' error from the UPDATE/transaction: DB unreachable, SQL syntax/constraint error, transaction abort, or JSON.stringify failure on approvalContext (e.g. circular structure throws TypeError before the UPDATE).

Common situations: Passing a non-serializable approvalContext object (circular refs, BigInt) so JSON.stringify throws; transient Postgres connection drops; schema drift where a column referenced by the UPDATE is missing; pool exhaustion.

Related errors

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