mastra-ai/mastra · error

Snapshot context not found for runId ${snapshot?.runId}

Error message

Snapshot context not found for runId ${snapshot?.runId}

What it means

mergeWorkflowStepResult mutates a WorkflowRunState snapshot to merge a step result, but requires snapshot.context to exist. When the snapshot is undefined, malformed (missing context), or loaded from storage in a legacy/partial shape, this error is thrown so the step result is not silently lost.

Source

Thrown at packages/core/src/storage/workflow-snapshot.ts:69

    waitingPaths: {},
    status: 'pending',
    runId,
  } as WorkflowRunState;
}

export function mergeWorkflowStepResult({
  snapshot,
  stepId,
  result,
  requestContext,
}: {
  snapshot: WorkflowRunState;
  stepId: string;
  result: StepResult<any, any, any, any>;
  requestContext: Record<string, any>;
}): Record<string, StepResult<any, any, any, any>> {
  if (!snapshot?.context) {
    throw new Error(`Snapshot context not found for runId ${snapshot?.runId}`);
  }

  const existingResult = snapshot.context[stepId];
  if (
    existingResult &&
    'output' in existingResult &&
    Array.isArray(existingResult.output) &&
    result &&
    typeof result === 'object' &&
    'output' in result &&
    Array.isArray(result.output)
  ) {
    const existingOutput = existingResult.output as unknown[];
    const newOutput = result.output as unknown[];
    const mergedOutput = [...existingOutput];
    const hasPendingMarker = newOutput.some(isPendingMarker);
    for (let i = 0; i < Math.max(existingOutput.length, newOutput.length); i++) {
      if (i < newOutput.length) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the runId is correct and the run exists in storage before merging
2. Re-create/initialize the snapshot so it has a context object before merging step results
3. Check the stored snapshot shape (e.g. log it) and migrate old records to include context
4. Wrap in try/catch and fall back to re-running the step or fetching a fresh snapshot

Example fix

// before
await workflow.commit({ runId: someId, results }); // someId not persisted
// after
const snapshot = await storage.getWorkflowRunState(runId);
if (!snapshot?.context) throw new Error(`Run ${runId} not found`);
await workflow.commit({ runId, results });

async function requireSnapshot(storage, runId) {
  const snapshot = await storage.getWorkflowRunState(runId);
  if (!snapshot?.context) throw new Error(`No persisted snapshot/context for run ${runId}`);
  return snapshot;
}

function hasContext(s: WorkflowRunState | undefined | null): s is WorkflowRunState & { context: Record<string, StepResult<any, any, any, any>> } {
  return !!s && typeof s === 'object' && !!s.context;
}

try {
  await mergeAndPersist(runId, stepId, result);
} catch (e) {
  if (String(e).includes('Snapshot context not found')) {
    logger.error('Workflow run snapshot missing', { runId, stepId });
    // re-create the run or surface a 404 to the caller
  } else throw e;
}

When it happens

Trigger: Calling context/getWorkflowRunState paths where the loaded snapshot is undefined (run not found) or its context field is missing; merging results into a snapshot retrieved from an old storage format.

Common situations: Querying a workflow run by ID that was never persisted or was deleted; a snapshot written by an older Mastra version without context; concurrent runs where the wrong runId was used.

Related errors

• Source thread with id ${sourceThreadId} not found
• Observational memory record not found: ${id}
• ATOMIC_STORAGE_OPERATIONS_NOT_SUPPORTED
• Cannot resume workflow: workflows store is required
• Cannot resume workflow: no snapshot found for runId ${this.r

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/21c4dc4d3fa4031e. Report an issue: GitHub.