{"record":{"id":"ed5219f9153188a2","repo":"mastra-ai/mastra","slug":"durable-agent-recover-snapshot-not-found","errorCode":"DURABLE_AGENT_RECOVER_SNAPSHOT_NOT_FOUND","errorMessage":"DurableAgent \"${this.name}\" recover(${runId}): no persisted workflow snapshot found. The run may have already completed or been cleaned up.","messagePattern":"DurableAgent \"(.+?)\" recover\\((.+?)\\): no persisted workflow snapshot found\\. The run may have already completed or been cleaned up\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/durable/durable-agent.ts","lineNumber":706,"sourceCode":"            ?.getLogger?.()\n            ?.warn?.(`[DurableAgent] recover(${runId}) failed to release recovery lease: ${error}`);\n        } finally {\n          if (localRecoveryClaims.get(key) === owner) localRecoveryClaims.delete(key);\n        }\n      },\n    };\n  }\n\n  async #loadRecoverableWorkflowInput(\n    workflowsStore: WorkflowsStorage,\n    runId: string,\n  ): Promise<DurableAgenticWorkflowInput> {\n    const persisted = await workflowsStore.getWorkflowRunById({\n      runId,\n      workflowName: DurableStepIds.AGENTIC_LOOP,\n    });\n    if (!persisted) {\n      throw new MastraError({\n        id: 'DURABLE_AGENT_RECOVER_SNAPSHOT_NOT_FOUND',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        text:\n          `DurableAgent \"${this.name}\" recover(${runId}): no persisted workflow snapshot found. ` +\n          `The run may have already completed or been cleaned up.`,\n        details: { agentName: this.name, runId },\n      });\n    }\n\n    const snapshot =\n      typeof persisted.snapshot === 'string'\n        ? (JSON.parse(persisted.snapshot) as WorkflowRunState)\n        : persisted.snapshot;\n    const workflowInput = snapshot?.context?.input as DurableAgenticWorkflowInput | undefined;\n    if (!workflowInput || workflowInput.__workflowKind !== 'durable-agent') {\n      throw new MastraError({\n        id: 'DURABLE_AGENT_RECOVER_INVALID_SNAPSHOT',","sourceCodeStart":688,"sourceCodeEnd":724,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/durable/durable-agent.ts#L688-L724","documentation":"#loadRecoverableWorkflowInput reads the persisted workflow run from the workflows store via getWorkflowRunById({ runId, workflowName: DurableStepIds.AGENTIC_LOOP }). If no persisted record exists, there is no snapshot to rebuild the durable workflow input from, so recover() throws this USER error. It means the runId has nothing recoverable behind it.","triggerScenarios":"Calling agent.recover(runId) when the workflows store has no run record for that runId under the AGENTIC_LOOP workflow — the run never started, already completed and was cleaned up, or the runId is wrong/typo'd.","commonSituations":"Recovering runs after a storage cleanup/retention job removed old snapshots; typo'd or stale runId from an old environment; pointing at a different storage backend than the one that recorded the run (dev DB vs prod DB).","solutions":["Confirm the runId exists in the workflows store (query the run by ID before recovering).","Verify the agent's workflowsStore points at the same storage that persisted the original run (env/config check).","If the run completed or was cleaned up, re-run the original task instead of recovering.","Recover within your retention window; extend snapshot retention if legitimate runs are being purged."],"exampleFix":"// before\nawait agent.recover(runId); // runId from last month, snapshot purged\n// after\nconst persisted = await workflowsStore.getWorkflowRunById({ runId, workflowName: DurableStepIds.AGENTIC_LOOP });\nif (!persisted) {\n  console.warn(`Run ${runId} not recoverable; restarting task`);\n  await restartTask();\n} else {\n  await agent.recover(runId);\n}","handlingStrategy":"validation","validationCode":"const persisted = await workflowsStore.getWorkflowRunById({ runId, workflowName: DurableStepIds.AGENTIC_LOOP });\nif (!persisted) throw new Error(`Run ${runId} has no persisted snapshot; cannot recover.`);","typeGuard":null,"tryCatchPattern":"try {\n  await agent.recover(runId);\n} catch (e) {\n  if (String(e?.id) === 'DURABLE_AGENT_RECOVER_SNAPSHOT_NOT_FOUND') {\n    await restartOriginalTask(runId); // snapshot gone; re-execute instead\n  } else throw e;\n}","preventionTips":["Check the workflows store for the runId before attempting recovery.","Keep storage retention long enough to cover your recovery window.","Point the agent at the same storage backend that recorded the run (env-specific config)."],"tags":["durable-agent","recovery","snapshot","storage","state-not-found"],"backgroundTag":"workflow-snapshot-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}