{"record":{"id":"b0e28275cc30225b","repo":"coleam00/Archon","slug":"failed-to-pause-workflow-run-for-wait-err-messa","errorCode":null,"errorMessage":"Failed to pause workflow run for wait: ${err.message}","messagePattern":"Failed to pause workflow run for wait: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/db/workflows.ts","lineNumber":1472,"sourceCode":"      }\n      if (pause.kind === 'started') {\n        await insertWorkflowEvent(query, {\n          workflow_run_id: id,\n          event_type: 'wait_started',\n          step_name: pause.stepName,\n          data: {\n            kind: parsedWaitContext.kind,\n            resume_at: parsedWaitContext.resumeAt,\n            ...(parsedWaitContext.kind === 'event' ? { event: parsedWaitContext.event } : {}),\n          },\n        });\n      }\n    });\n  } catch (error) {\n    if (error instanceof Error && error.message.startsWith('Workflow run not found')) throw error;\n    const err = error as Error;\n    getLog().error({ err, workflowRunId: id }, 'db.workflow_run_wait_pause_failed');\n    throw new Error(`Failed to pause workflow run for wait: ${err.message}`);\n  }\n}\n\n/** Atomically consume one exact wait cursor and persist its completed node snapshot. */\nexport async function clearWorkflowWaitContext(\n  id: string,\n  waitContext: WorkflowWaitContext,\n  completion: WorkflowWaitCompletion\n): Promise<{ cleared: boolean }> {\n  const nodeExpr =\n    getDatabaseType() === 'postgresql'\n      ? \"metadata->'wait'->>'nodeId'\"\n      : \"json_extract(metadata, '$.wait.nodeId')\";\n  const resumeAtExpr =\n    getDatabaseType() === 'postgresql'\n      ? \"metadata->'wait'->>'resumeAt'\"\n      : \"json_extract(metadata, '$.wait.resumeAt')\";\n  const clearWait =","sourceCodeStart":1454,"sourceCodeEnd":1490,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/core/src/db/workflows.ts#L1454-L1490","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the inner err.message: FK or event errors point to the insertWorkflowEvent step — verify the run row and event payload","Validate waitContext shape (kind, stepName, cursor) before calling; the function expects a parsed, schema-valid wait context","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","If the run has since completed or paused, expect the 'Workflow run not found' variant instead — handle that case separately"],"exampleFix":"// before\nawait pauseWorkflowRunForWait(id, rawWait); // rawWait unvalidated\n// after\nconst parsed = waitContextSchema.safeParse(rawWait);\nif (!parsed.success) throw new Error(`invalid wait context: ${parsed.error.message}`);\ntry {\n  await pauseWorkflowRunForWait(id, parsed.data);\n} catch (err) {\n  if (!err.message.startsWith('Workflow run not found')) logger.error({ id, err }, 'wait pause failed');\n  throw err;\n}","handlingStrategy":"try-catch","validationCode":"const parsed = waitContextSchema.safeParse(waitCtx);\nif (!parsed.success) throw new Error('invalid wait context');\nJSON.stringify(parsed.data); // serializability check\nconst run = await getWorkflowRun(id);\nif (run?.status !== 'running') throw new Error('run not running');","typeGuard":"function isWaitPauseFailure(e: unknown): e is Error {\n  return e instanceof Error && e.message.startsWith('Failed to pause workflow run for wait:');\n}","tryCatchPattern":"try {\n  await pauseWorkflowRunForWait(id, waitCtx);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Workflow run not found')) throw e;\n  if (/ECONNREFUSED|deadlock|serialization|ETIMEDOUT/i.test(e.message)) {\n    return retryWithBackoff(() => pauseWorkflowRunForWait(id, waitCtx));\n  }\n  throw e;\n}","preventionTips":["Validate the wait context against the schema before arming","Keep the whole pause+event sequence in one transaction so retries are safe","Verify the run row exists before the call to avoid FK failures on wait events","Distinguish 'not found' (expected race) from wrapped DB errors when handling"],"tags":["database","workflow","wait","transaction","error-wrapping"],"backgroundTag":"database-operation-failed","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}