# 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 has not 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:

```typescript
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

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

### Using step ID

```typescript
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:

```typescript
// 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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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 cannot time travel to a workflow that is currently running:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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.

```typescript
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):

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

## Related

- [Snapshots](https://mastra.ai/docs/workflows/snapshots)
- [Suspend & Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
- [Error Handling](https://mastra.ai/docs/workflows/error-handling)
- [Control Flow](https://mastra.ai/docs/workflows/control-flow)