coleam00/Archon · error

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

Error message

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

What it means

Wrap-around error for unexpected failures while pausing a run for a time/event wait. The intentional no-match error ('Workflow run not found...') is re-thrown as-is; any other error from the transaction — including inserting wait events or the wait-context JSON write — is logged as db.workflow_run_wait_pause_failed and re-thrown with the inner message.

Source

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

      }
      if (pause.kind === 'started') {
        await insertWorkflowEvent(query, {
          workflow_run_id: id,
          event_type: 'wait_started',
          step_name: pause.stepName,
          data: {
            kind: parsedWaitContext.kind,
            resume_at: parsedWaitContext.resumeAt,
            ...(parsedWaitContext.kind === 'event' ? { event: parsedWaitContext.event } : {}),
          },
        });
      }
    });
  } 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_wait_pause_failed');
    throw new Error(`Failed to pause workflow run for wait: ${err.message}`);
  }
}

/** Atomically consume one exact wait cursor and persist its completed node snapshot. */
export async function clearWorkflowWaitContext(
  id: string,
  waitContext: WorkflowWaitContext,
  completion: WorkflowWaitCompletion
): Promise<{ cleared: boolean }> {
  const nodeExpr =
    getDatabaseType() === 'postgresql'
      ? "metadata->'wait'->>'nodeId'"
      : "json_extract(metadata, '$.wait.nodeId')";
  const resumeAtExpr =
    getDatabaseType() === 'postgresql'
      ? "metadata->'wait'->>'resumeAt'"
      : "json_extract(metadata, '$.wait.resumeAt')";
  const clearWait =

View on GitHub (pinned to 0773b97458)

Solutions

1. Read the inner err.message: FK or event errors point to the insertWorkflowEvent step — verify the run row and event payload
2. Validate waitContext shape (kind, stepName, cursor) before calling; the function expects a parsed, schema-valid wait context
3. Check DB health and retry with backoff for transient transaction failures; the transaction is atomic so a retry is safe if the run is still running
4. If the run has since completed or paused, expect the 'Workflow run not found' variant instead — handle that case separately

Example fix

// before
await pauseWorkflowRunForWait(id, rawWait); // rawWait unvalidated
// after
const parsed = waitContextSchema.safeParse(rawWait);
if (!parsed.success) throw new Error(`invalid wait context: ${parsed.error.message}`);
try {
  await pauseWorkflowRunForWait(id, parsed.data);
} catch (err) {
  if (!err.message.startsWith('Workflow run not found')) logger.error({ id, err }, 'wait pause failed');
  throw err;
}

const parsed = waitContextSchema.safeParse(waitCtx);
if (!parsed.success) throw new Error('invalid wait context');
JSON.stringify(parsed.data); // serializability check
const run = await getWorkflowRun(id);
if (run?.status !== 'running') throw new Error('run not running');

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

try {
  await pauseWorkflowRunForWait(id, waitCtx);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Workflow run not found')) throw e;
  if (/ECONNREFUSED|deadlock|serialization|ETIMEDOUT/i.test(e.message)) {
    return retryWithBackoff(() => pauseWorkflowRunForWait(id, waitCtx));
  }
  throw e;
}

When it happens

Trigger: pauseWorkflowRunForWait(id, waitContext) throws a non-'not found' error inside its transaction: DB connection failure, constraint violation on insertWorkflowEvent (e.g. foreign-key on workflow_run_id), invalid parsedWaitContext JSON, or transaction abort between the UPDATE and the wait_started event insert.

Common situations: Malformed wait context (missing stepName or kind) failing downstream validation; FK violation when the run row vanished mid-transaction; transient connectivity drop during the multi-statement transaction; non-serializable wait context breaking JSON.stringify.

Related errors

• Failed to cancel fan-out run: ${err.message}
• Failed to pause workflow run: ${err.message}
• Failed to clear workflow wait: ${err.message}
• Failed to abandon workflow run ${run.id}: ${err.message}
• Failed to get workflow run: ${err.message}

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