{"record":{"id":"87cee5bc25f1ebf2","repo":"mastra-ai/mastra","slug":"agent-resume-no-snapshot-found","errorCode":"AGENT_RESUME_NO_SNAPSHOT_FOUND","errorMessage":"Agent \"${this.name}\" ${method}() could not find a suspended run for runId \"${runId}\". ${hasStorage ? `The run may have already completed, never suspended, or the runId is invalid. ` : `No storage is configured on this Mastra instance, so workflow snapshots can't be persisted. Register the agent on a Mastra instance with persistent storage (e.g. PostgreSQL, LibSQL). See https://mastra.ai/docs/storage. `}Ensure you are calling ${method}() only with a runId from a currently-suspended run.","messagePattern":"Agent \"(.+?)\" (.+?)\\(\\) could not find a suspended run for runId \"(.+?)\"\\. (.+?)Ensure you are calling (.+?)\\(\\) only with a runId from a currently-suspended run\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/agent.ts","lineNumber":6728,"sourceCode":"    }\n    return value;\n  }\n\n  /**\n   * Loads the agentic-loop workflow snapshot for resume, or throws an actionable error.\n   * Used by resumeStream and resumeGenerate to fail fast at the agent boundary.\n   * @internal\n   */\n  async #loadAgenticLoopSnapshotOrThrow({ runId, method }: { runId: string; method: string }) {\n    const effectiveMastra = this.#mastra ?? (await this.#getOrCreateEphemeralMastra());\n    const workflowsStore = await effectiveMastra?.getStorage()?.getStore('workflows');\n    const existingSnapshot = await waitForSuspendedSnapshot(workflowsStore, 'agentic-loop', runId, {\n      missingSnapshotGraceReads: 3,\n    });\n\n    if (!existingSnapshot) {\n      const hasStorage = !!workflowsStore;\n      throw new MastraError({\n        id: 'AGENT_RESUME_NO_SNAPSHOT_FOUND',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        text:\n          `Agent \"${this.name}\" ${method}() could not find a suspended run for runId \"${runId}\". ` +\n          (hasStorage\n            ? `The run may have already completed, never suspended, or the runId is invalid. `\n            : `No storage is configured on this Mastra instance, so workflow snapshots can't be persisted. Register the agent on a Mastra instance with persistent storage (e.g. PostgreSQL, LibSQL). See https://mastra.ai/docs/storage. `) +\n          `Ensure you are calling ${method}() only with a runId from a currently-suspended run.`,\n        details: {\n          runId,\n          agentName: this.name,\n          hasStorage,\n        },\n      });\n    }\n\n    return existingSnapshot;","sourceCodeStart":6710,"sourceCodeEnd":6746,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/agent.ts#L6710-L6746","documentation":"A MastraError (id AGENT_RESUME_NO_SNAPSHOT_FOUND) thrown when `agent.resume()`/`approve()`/`decline()` (method) is called with a runId for which no suspended workflow snapshot ('agentic-loop' workflow) exists in the workflows store. The message distinguishes storage-backed cases (run completed/never suspended/invalid id) from the no-storage case where snapshots can't persist at all.","triggerScenarios":"Resuming with a runId that has already completed; resuming a run that never actually suspended; passing an invalid/fabricated runId; calling resume on an agent whose Mastra instance has no persistent storage configured (snapshot never written); racing resume before the suspend snapshot grace-reads (3) complete.","commonSituations":"Client retries resuming an already-finished run after a timeout; forgetting to configure PostgreSQL/LibSQL storage in dev; copying runIds across environments; resuming from a stale id persisted on the client after the loop ended.","solutions":["Configure persistent storage on the Mastra instance (e.g. `new Mastra({ storage: new LibSQLStore(...) })`) if none is set","Capture the runId returned when the run actually suspends (from the suspend event/snapshot), not a client-guessed id","Check the run's status before resuming — if it already completed, start a new run instead","Ensure you don't resume twice; the first resume completes the run and invalidates the snapshot","Verify you're pointing at the same storage backend/environment that recorded the run"],"exampleFix":"// before\nconst mastra = new Mastra({ agents: { myAgent } }); // no storage\n// after\nconst mastra = new Mastra({ agents: { myAgent }, storage: new PostgresStore({ connectionString }) });","handlingStrategy":"validation","validationCode":"async function canResume(mastra, agentName, runId) {\n  if (!mastra.getStorage?.()) throw new Error('configure persistent storage before using suspend/resume');\n  const run = await mastra.getStorage()?.getWorkflowRunById?.('agentic-loop', runId);\n  if (!run) throw new Error(`unknown runId ${runId}`);\n  if (run.status !== 'suspended') throw new Error(`run ${runId} is ${run.status}, not suspended`);\n}","typeGuard":"function isSuspendedRun(run) {\n  return !!run && typeof run === 'object' && run.status === 'suspended' && typeof run.runId === 'string';\n}","tryCatchPattern":"try {\n  return await agent.resume({ runId });\n} catch (e) {\n  if (e?.id === 'AGENT_RESUME_NO_SNAPSHOT_FOUND') {\n    logger.warn(`run ${runId} not resumable (completed/invalid/no storage); starting new run`);\n    return startNewRun();\n  }\n  throw e;\n}","preventionTips":["Always configure persistent storage (Postgres/LibSQL) on Mastra when using suspend/resume","Only resume with runIds captured from the actual suspend event","Check run status before resume; treat completed runs as terminal","Persist runIds server-side with the run state, not as long-lived client tokens"],"tags":["agent","resume","suspend","workflow-snapshot","storage","runid"],"backgroundTag":"suspend-resume-snapshot-missing","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}