What causes "Failed to claim write-back apply: ${err.message}" in coleam00/Archon?

Read the `db.workflow_run_claim_writeback_failed` log for the driver-level cause

Failed to claim write-back apply: ${err.message}

Error message

Failed to claim write-back apply: ${err.message}

What it means

Thrown by the write-back apply claim function when the conditional UPDATE that sets `metadata.writeback_apply_claimed = true` fails. This claim (R2-F4) must be acquired before mutating the live root; a driver/SQL failure is logged as `db.workflow_run_claim_writeback_failed` and rethrown with this message. `{claimed:false}` means another process already claimed it or the run no longer matches — that is a normal outcome, not this error.

Source

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

 */
export async function claimWriteback(id: string): Promise<{ claimed: boolean }> {
  const dialect = getDialect();
  const extract =
    getDatabaseType() === 'postgresql'
      ? "metadata->>'writeback_apply_claimed'"
      : "json_extract(metadata, '$.writeback_apply_claimed')";
  try {
    const result = await pool.query(
      `UPDATE remote_agent_workflow_runs
       SET metadata = ${dialect.jsonMerge('metadata', 2)}
       WHERE id = $1 AND (${extract} IS NULL)`,
      [id, JSON.stringify({ writeback_apply_claimed: true })]
    );
    return { claimed: (result.rowCount ?? 0) > 0 };
  } catch (error) {
    const err = error as Error;
    getLog().error({ err, workflowRunId: id }, 'db.workflow_run_claim_writeback_failed');
    throw new Error(`Failed to claim write-back apply: ${err.message}`);
  }
}

/**
 * Release a previously-claimed write-back apply (R2-F4) after the apply FAILED, so a
 * subsequent `workflow resume` can re-claim and retry. Explicit-null so SQLite's
 * json_patch removes the key (Postgres `||` sets JSON null); `claimWriteback`'s
 * `IS NULL` check treats both as unclaimed. Best-effort — a failure here leaves the
 * claim set (the volume is preserved regardless; the operator reconciles manually).
 */
export async function releaseWritebackClaim(id: string): Promise<void> {
  const dialect = getDialect();
  await pool.query(
    `UPDATE remote_agent_workflow_runs
     SET metadata = ${dialect.jsonMerge('metadata', 2)}
     WHERE id = $1`,
    [id, JSON.stringify({ writeback_apply_claimed: null })]
  );

View on GitHub (pinned to 0773b97458)

Solutions

Read the `db.workflow_run_claim_writeback_failed` log for the driver-level cause
Retry the claim — losing a race returns claimed:false and a transient DB failure can be retried safely
Verify metadata JSON integrity and dialect-specific update SQL if merge errors appear
Check connection pool health before re-running the write-back apply flow

Example fix

// before
await claimWritebackApply(runId); // throws on DB error
// after
let claim;
try {
  claim = await claimWritebackApply(runId);
} catch (e) {
  throw new Error(`write-back apply aborted: claim step failed: ${String(e)}`);
}
if (!claim.claimed) return; // already claimed elsewhere — skip apply

Defensive patterns

Strategy: try-catch

Validate before calling

// check the run is still eligible to claim before apply
const run = await getWorkflowRun(id);
const claimable = run != null && !run.metadata?.writeback_apply_claimed;

Type guard

function isUnclaimed(run: WorkflowRun | undefined): boolean {
  return run != null && run.metadata?.writeback_apply_claimed !== true;
}

Try / catch

let claimed: boolean;
try {
  claimed = (await claimWritebackApply(id)).claimed;
} catch (error) {
  log.error({ id, err: error }, 'claim failed; aborting write-back apply');
  throw error;
}
if (!claimed) return; // someone else owns the apply

Prevention

Always claim before mutating the live root (R2-F4); never skip the claim
Release the claim on apply failure via the release API so retries can re-claim
Keep apply+claim flows short-lived to reduce lock windows
Alert on `db.workflow_run_claim_writeback_failed` — it blocks the apply pipeline

When it happens

Trigger: Calling the claim before applying a container write-back when the DB is unreachable, the transaction/UPDATE errors, the metadata column rejects the JSON merge, or lock contention kills the statement.

Common situations: Two concurrent resume processes contending on the same run row; database connection drop mid-apply pipeline; metadata JSON corrupted so the merge update fails.

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/94bad36b9d423446. Report an issue: GitHub.