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

Check the logged `db.workflow_wait_clear_failed` entry for the underlying driver message and fix that root cause first

Failed to clear workflow wait: ${err.message}

Error message

Failed to clear workflow wait: ${err.message}

What it means

Thrown by clearWorkflowWait in packages/core/src/db/workflows.ts when the transactional UPDATE that removes the `metadata.wait` object (and inserts wait_completed/wait_expired events) fails against SQLite or PostgreSQL. It is a contextual rethrow: the original driver error is logged under `db.workflow_wait_clear_failed` and its message is embedded. The function returns `{cleared:false}` (not an error) when the wait row simply does not match, so this throw always means a database-level failure, not a missed match.

Source

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

        data: completion.result,
      });
      await insertWorkflowEvent(query, {
        workflow_run_id: id,
        event_type: 'node_completed',
        step_name: completion.stepName,
        data: {
          type: 'wait',
          duration_ms: completion.result.waited_ms,
          node_output: JSON.stringify(completion.result),
          structured_output: completion.result,
        },
      });
      return { cleared: true };
    });
  } catch (error) {
    const err = error as Error;
    getLog().error({ err, workflowRunId: id }, 'db.workflow_wait_clear_failed');
    throw new Error(`Failed to clear workflow wait: ${err.message}`);
  }
}

/** Return a bounded set of time/deadline waits eligible for a resume claim. */
export async function listDueWorkflowContinuations(
  now: Date,
  limit: number
): Promise<WorkflowRun[]> {
  const resumeAt =
    getDatabaseType() === 'postgresql'
      ? "metadata->'wait'->>'resumeAt'"
      : "json_extract(metadata, '$.wait.resumeAt')";
  const signaledAt =
    getDatabaseType() === 'postgresql'
      ? "metadata->'wait'->>'signaledAt'"
      : "json_extract(metadata, '$.wait.signaledAt')";
  const scheduledResumeAt =
    getDatabaseType() === 'postgresql'

View on GitHub (pinned to 0773b97458)

Solutions

Check the logged `db.workflow_wait_clear_failed` entry for the underlying driver message and fix that root cause first
Verify database connectivity (server up, pool not exhausted) and retry the resume
Confirm the configured database type (sqlite/postgresql) matches the actual schema so JSON-path expressions are valid
If disk-full/read-only, free space or restore write access before resuming

Example fix

// before
clearWorkflowWait(runId, waitCtx, completion); // throws opaque 'Failed to clear workflow wait: ...'
// after
try {
  const { cleared } = await clearWorkflowWait(runId, waitCtx, completion);
  if (!cleared) logger.warn({ runId }, 'wait already cleared or status changed');
} catch (e) {
  logger.error({ runId, cause: e }, 'clearing wait failed; will retry resume');
}

Defensive patterns

Strategy: try-catch

Validate before calling

// before calling
classic check: ensure the run exists and is paused with the expected wait
const run = await getWorkflowRun(id);
const canClear = run?.status === 'running' && run.metadata?.wait?.nodeId === waitContext.nodeId;

Type guard

function isEventOrTimeWait(w: unknown): w is WorkflowWaitContext {
  return typeof w === 'object' && w !== null && 'kind' in w && 'nodeId' in w && 'resumeAt' in w;
}

Try / catch

try {
  const { cleared } = await clearWorkflowWait(id, waitContext, completion);
  if (!cleared) log.info({ id }, 'wait not matched; run state moved on');
} catch (error) {
  const cause = (error as Error).message.replace('Failed to clear workflow wait: ', '');
  log.error({ id, cause }, 'clear workflow wait failed');
  throw error; // resume pipeline should handle retry
}

Prevention

Keep the database reachable and pool sized for resume traffic
Never edit `metadata.wait` JSON out-of-band; use the library APIs
Pin one database engine per deployment so dialect JSON paths stay valid
Monitor `db.workflow_wait_clear_failed` log events as an SLO signal

When it happens

Trigger: Calling clearWorkflowWait(id, waitContext, completion) when the database connection is down, the underlying `remote_agent_workflow_runs` UPDATE or insertWorkflowEvent calls fail (lock timeout, SQL error, JSON-path expression invalid for the configured dialect), or the withTransaction callback rejects.

Common situations: Postgres restarted or connection pool exhausted during a workflow resume; schema drift so metadata columns/dialect JSON functions mismatch; a database in read-only mode (disk full, replica); concurrent transaction lock contention on the run row.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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