mastra-ai/mastra · error · MastraError

WORKFLOW_WAIT_FOR_EVENT_REMOVED

WORKFLOW_WAIT_FOR_EVENT_REMOVED

Error message

waitForEvent has been removed. Please use suspend & resume flow instead. See https://mastra.ai/en/docs/workflows/suspend-and-resume for more details.

What it means

`Workflow.waitForEvent()` is no longer implemented: calling it throws immediately. The event-waiting API was removed from Mastra workflows in favor of the suspend & resume pattern, which persists the run and resumes it when an external event arrives.

Source

Thrown at packages/core/src/workflows/workflow.ts:2060

      TState,
      TInput,
      TOutput,
      TPrevSchema,
      TRequestContext
    >;
  }

  /**
   * @deprecated waitForEvent has been removed. Please use suspend/resume instead.
   */
  waitForEvent<TStepState, TStepInputSchema extends TPrevSchema, TStepId extends string, TSchemaOut>(
    _event: string,
    _step: Step<TStepId, SubsetOf<TStepState, TState>, TStepInputSchema, TSchemaOut, any, any, TEngineType>,
    _opts?: {
      timeout?: number;
    },
  ) {
    throw new MastraError({
      id: 'WORKFLOW_WAIT_FOR_EVENT_REMOVED',
      domain: ErrorDomain.MASTRA_WORKFLOW,
      category: ErrorCategory.USER,
      text: 'waitForEvent has been removed. Please use suspend & resume flow instead. See https://mastra.ai/en/docs/workflows/suspend-and-resume for more details.',
    });
  }

  map(
    mappingConfig:
      | {
          [k: string]:
            | {
                step:
                  | Step<string, any, any, any, any, any, TEngineType, any>
                  | Step<string, any, any, any, any, any, TEngineType, any>[];
                path: string;
              }
            | { value: any; schema: PublicSchema<any> }

View on GitHub (pinned to 75dd419e61)

Solutions

Replace waitForEvent with `await step.suspend()` and a later `run.resume({ resumeData })` triggered by your external event handler.
Follow the suspend-and-resume docs: https://mastra.ai/en/docs/workflows/suspend-and-resume
Model the 'event' as resumeData payload passed to the suspended step.
Remove any `_opts.timeout` usage and implement timeouts yourself (e.g. a timer step that resumes with an 'expired' payload).

Example fix

// before
workflow.waitForEvent('approval', approvalStep, { timeout: 3600 });
// after
approvalStep.suspend();
// in your event handler:
await run.resume({ stepId: 'approvalStep', resumeData: { approved: true } });

Defensive patterns

Strategy: type-guard

Validate before calling

declare module './workflow' { interface Workflow { waitForEvent?: never } }
// or a runtime check during migration:
if ('waitForEvent' in workflow && typeof workflow.waitForEvent === 'function') {
  throw new Error('migrate waitForEvent to suspend/resume');
}

Try / catch

try {
  // legacy call path
  (workflow as any).waitForEvent(name, step, opts);
} catch (e) {
  if (String(e?.message).includes('waitForEvent has been removed')) {
    // fall back to suspend/resume flow
  } else throw e;
}

Prevention

Grep for waitForEvent during Mastra upgrades and migrate to suspend/resume.
Use TypeScript overload types that no longer expose waitForEvent.
Follow the official suspend-and-resume docs for human-in-the-loop patterns.

When it happens

Trigger: Any call to `workflow.waitForEvent(eventName, step, { timeout })` on a workflow built with the current engine; typically code migrated from an older Mastra version that used waitForEvent for human-in-the-loop or external approval flows.

Common situations: Upgrading Mastra and old workflow code still calling waitForEvent; following outdated tutorials/snippets; porting Temporal-style signal/wait patterns into Mastra.

Related errors

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