Time travel

Trust: ★★★☆☆ (0.90) · 0 validations · developer_reference

Published: 2026-05-10 · Source: crawler_authoritative

Tình huống

Mastra workflow feature for re-executing workflows from any specific step using stored snapshots or custom context, enabling debugging, error recovery, and isolated step testing.

Insight

The timeTravel() method re-executes a workflow from a specified step by loading existing snapshots from storage, reconstructing step results from snapshot data or provided context, then executing from the target step forward. Time travel requires storage to be configured. The target step can be specified using a step reference (step2), step ID string (‘step2’), or for nested workflows using dot notation (‘nestedWorkflow.step3’) or array notation ([‘nestedWorkflow’, ‘step3’]). The context object contains step results keyed by step ID, each including status (‘success’, ‘failed’, ‘suspended’), payload (input data), output (output data), startedAt/endedAt timestamps, suspendPayload (for suspended steps), and resumePayload (for resumed steps). The nestedStepsContext object handles context for steps inside nested workflows. The initialState parameter sets workflow-level state during time travel. The timeTravelStream() method provides streaming events during execution via fullStream. Error scenarios include attempting time travel on a running workflow (throws ‘This workflow run is still running, cannot time travel’), invalid step IDs (throws ‘Time travel target step not found in execution graph’), and when validateInputs is enabled, input validation against step schemas.

Hành động

Call run.timeTravel() on a workflow run instance. Basic syntax: run.timeTravel({ step: ‘stepId’, inputData: {…} }). For step references: pass the step object directly. For nested workflows: use dot notation (step: ‘nestedWorkflow.step3’), array of IDs, or array of references. Provide context for previous steps using the context parameter: { step1: { status: ‘success’, payload: {…}, output: {…}, startedAt: Date.now(), endedAt: Date.now() } }. For nested workflows with mixed context, use context for parent steps and nestedStepsContext for nested workflow steps. Re-run failed workflows by checking result.status === ‘failed’, then calling timeTravel with corrected inputData. Resume suspended workflows using resumeData parameter. Use timeTravelStream() for streaming: const stream = run.timeTravelStream({…}); for await (const event of stream.fullStream) {…}. Set initial state with initialState: { counter: 5, metadata: {…} }. Prerequisites: storage must be configured; workflow run must exist and not be currently running.

Kết quả

Returns a workflow result object with status (‘success’, ‘failed’, ‘suspended’), or streaming events via timeTravelStream(). Successfully re-executes the workflow from the target step, using provided context to reconstruct previous step states, then continues to completion.

Điều kiện áp dụng

Requires storage to be configured since it relies on persisted workflow snapshots. Cannot time travel to a workflow that is currently running.

---

Nội dung gốc (Original)

Time travel

Time travel allows you to re-execute a workflow starting from any specific step, using either stored snapshot data or custom context you provide. This is useful for debugging failed workflows, testing individual steps with different inputs, or recovering from errors without re-running the entire workflow. You can also use time travel to execute a workflow that hasn’t been run yet, starting from any specific step.

How time travel works

When you call timeTravel() on a workflow run:

1. The workflow loads the existing snapshot from storage (if available)
2. Step results before the target step are reconstructed from the snapshot or provided context
3. Execution begins from the specified step with the provided or reconstructed input data
4. The workflow continues to completion from that point forward

Time travel requires storage to be configured since it relies on persisted workflow snapshots.

Basic usage

Use run.timeTravel() to re-execute a workflow from a specific step:

import { mastra } from './mastra'
 
const workflow = mastra.getWorkflow('myWorkflow')
const run = await workflow.createRun()
 
const result = await run.timeTravel({
  step: 'step2',
  inputData: { previousStepResult: 'custom value' },
})

Specifying the target step

You can specify the target step using either a step reference or a step ID:

Using step reference

const result = await run.timeTravel({
  step: step2,
  inputData: { value: 10 },
})

Using step ID

const result = await run.timeTravel({
  step: 'step2',
  inputData: { value: 10 },
})

Nested workflow steps

For steps inside nested workflows, use dot notation, an array of step IDS or an array of step references:

// Using dot notation
const result = await run.timeTravel({
  step: 'nestedWorkflow.step3',
  inputData: { value: 10 },
})
 
// Using array of step IDs
const result = await run.timeTravel({
  step: ['nestedWorkflow', 'step3'],
  inputData: { value: 10 },
})
 
// Using array of step references
const result = await run.timeTravel({
  step: [nestedWorkflow, step3],
  inputData: { value: 10 },
})

Providing execution context

You can provide context to specify the state of previous steps when time traveling:

const result = await run.timeTravel({
  step: 'step2',
  context: {
    step1: {
      status: 'success',
      payload: { value: 0 },
      output: { step1Result: 2 },
      startedAt: Date.now(),
      endedAt: Date.now(),
    },
  },
})

The context object contains step results keyed by step ID. Each step result includes:

• status: The step’s execution status (success, failed, suspended)
• payload: The input data passed to the step
• output: The step’s output data (for successful steps)
• startedAt: Timestamp when the step started
• endedAt: Timestamp when the step ended (for completed steps)
• suspendPayload: Data passed to suspend() (for suspended steps)
• resumePayload: Data passed to resume() (for resumed steps)

Re-running failed workflows

Time travel is particularly useful for debugging and recovering from failed workflow executions:

const workflow = mastra.getWorkflow('myWorkflow')
const run = await workflow.createRun()
 
// Initial run fails at step2
const failedResult = await run.start({
  inputData: { value: 1 },
})
 
if (failedResult.status === 'failed') {
  // Re-run from step2 with corrected input
  const recoveredResult = await run.timeTravel({
    step: 'step2',
    inputData: { step1Result: 5 }, // Provide corrected input
  })
}

Time travel with suspended workflows

You can time travel to resume a suspended workflow from an earlier step:

const run = await workflow.createRun()
 
// Start workflow - suspends at promptAgent step
const initialResult = await run.start({
  inputData: { input: 'test' },
})
 
if (initialResult.status === 'suspended') {
  // Time travel back to an earlier step with resume data
  const result = await run.timeTravel({
    step: 'getUserInput',
    resumeData: {
      userInput: 'corrected input',
    },
  })
}

Streaming time travel results

Use timeTravelStream() to receive streaming events during time travel execution:

const run = await workflow.createRun()
 
const stream = run.timeTravelStream({
  step: 'step2',
  inputData: { value: 10 },
})
 
for await (const event of stream.fullStream) {
  console.log(event.type, event.payload)
}
 
const result = await stream.result
 
if (result.status === 'success') {
  console.log(result.result)
}

Time travel with initial state

You can provide initial state when time traveling to set workflow-level state:

const result = await run.timeTravel({
  step: 'step2',
  inputData: { value: 10 },
  initialState: {
    counter: 5,
    metadata: { source: 'time-travel' },
  },
})

Error handling

Time travel throws errors in specific situations:

Running workflow

You can’t time travel to a workflow that’s currently running:

try {
  await run.timeTravel({ step: 'step2' })
} catch (error) {
  // "This workflow run is still running, cannot time travel"
}

Invalid step ID

Time travel throws if the target step doesn’t exist in the workflow:

try {
  await run.timeTravel({ step: 'nonExistentStep' })
} catch (error) {
  // "Time travel target step not found in execution graph: 'nonExistentStep'. Verify the step id/path."
}

Invalid input data

When validateInputs is enabled, time travel validates the input data against the step’s schema:

try {
  await run.timeTravel({
    step: 'step2',
    inputData: { invalidField: 'value' },
  })
} catch (error) {
  // "Invalid inputData: \n- step1Result: Required"
}

Nested workflows context

When time traveling into a nested workflow, you can provide context for both the parent and nested workflow steps:

const result = await run.timeTravel({
  step: 'nestedWorkflow.step3',
  context: {
    step1: {
      status: 'success',
      payload: { value: 0 },
      output: { step1Result: 2 },
      startedAt: Date.now(),
      endedAt: Date.now(),
    },
    nestedWorkflow: {
      status: 'running',
      payload: { step1Result: 2 },
      startedAt: Date.now(),
    },
  },
  nestedStepsContext: {
    nestedWorkflow: {
      step2: {
        status: 'success',
        payload: { step1Result: 2 },
        output: { step2Result: 3 },
        startedAt: Date.now(),
        endedAt: Date.now(),
      },
    },
  },
})

Use cases

Debugging failed steps

Re-run a failed step with the same or modified input to diagnose issues:

const result = await run.timeTravel({
  step: failedStepId,
  context: originalContext, // Use context from the failed run
})

Testing step logic on new workflow run

Test individual steps with specific inputs on a new workflow run, useful for testing a step logic without starting workflow execution from the beginning.

const result = await run.timeTravel({
  step: 'processData',
  inputData: { testData: 'specific test case' },
})

Recovering from transient failures

Re-run steps that failed due to temporary issues (network errors, rate limits):

// After fixing the external service issue
const result = await run.timeTravel({
  step: 'callExternalApi',
  inputData: savedInputData,
})

Related

• Snapshots
• Suspend & Resume
• Error Handling
• Control Flow

Liên kết

• Nền tảng: Dev Framework · Mastra
• Nguồn: https://mastra.ai/docs/workflows/time-travel

Xem thêm:

• Workflow state
• Snapshots - Mastra Workflow State Persistence
• Control flow
• Suspend & Resume Workflows
• Error Handling in Mastra Workflows