mastra-ai/mastra · error · Error

Mastra instance with pubsub is required for workflow executi

Error message

Mastra instance with pubsub is required for workflow execution

What it means

The evented workflow engine coordinates runs through a pubsub (publishing workflow.start/step events and subscribing for completion). The workflow's Mastra instance either is not set or has no pubsub configured, so evented execution cannot proceed and the library throws before starting the run.

Source

Thrown at packages/core/src/workflows/evented/workflow.ts:1950

      requestContext: requestContext.toJSON(),
      activePaths: [],
      activeStepsPath: {},
      suspendedPaths: {},
      resumeLabels: {},
      waitingPaths: {},
      timestamp: Date.now(),
    };
    await workflowsStore?.persistWorkflowSnapshot({
      workflowName: this.workflowId,
      runId: this.runId,
      resourceId: this.resourceId,
      snapshot: this.executionEngine.options?.pruneSnapshot
        ? this.executionEngine.options.pruneSnapshot({ snapshot: initialRunSnapshot, workflowStatus: 'running' })
        : initialRunSnapshot,
    });

    if (!this.mastra?.pubsub) {
      throw new Error('Mastra instance with pubsub is required for workflow execution');
    }

    this.setupAbortHandler();

    // The evented engine runs steps from serialized pubsub events, which can't
    // carry the non-serializable AISpan. Create the WORKFLOW_RUN span here and
    // hold it on Mastra keyed by runId; the event processor nests each step's
    // spans under it (see `WorkflowEventProcessor.resolveRunTracingContext`).
    const workflowSpan = getOrCreateSpan({
      type: SpanType.WORKFLOW_RUN,
      name: `workflow run: '${this.workflowId}'`,
      entityType: EntityType.WORKFLOW_RUN,
      entityId: this.workflowId,
      entityName: this.workflowId,
      input: inputDataToUse,
      metadata: { resourceId: this.resourceId, runId: this.runId },
      tracingPolicy: this.tracingPolicy,
      tracingContext,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass an eventing config with a pubsub to the Mastra constructor: new Mastra({ ..., server: { experimentalIsEvented: true } }) or the pubsub option for your deployment
2. Register the workflow on the Mastra instance (mastra.addWorkflow(workflow)) so this.mastra is populated
3. Verify you are importing/using the evented workflow path intentionally; if you don't need eventing, use the standard workflow instead

Example fix

// before
export const mastra = new Mastra({ workflows: { myWorkflow } });
// after
export const mastra = new Mastra({
  workflows: { myWorkflow },
  server: { experimentalIsEvented: true },
});

if (!mastra.getPubsub?.() && !('pubsub' in mastra)) {
  throw new Error('Mastra must be configured with pubsub for evented workflows');
}

function hasPubsub(mastra) {
  return Boolean(mastra && 'pubsub' in mastra && mastra.pubsub);
}

try {
  await run.start({ inputData });
} catch (e) {
  if (e.message.includes('pubsub is required')) {
    throw new Error('Configure eventing (pubsub) on your Mastra instance before using evented workflows', { cause: e });
  }
  throw e;
}

When it happens

Trigger: Calling start() on an evented workflow where this.mastra is undefined or this.mastra.pubsub is undefined — typically because the workflow was never registered on a Mastra instance with an evented pubsub (e.g. no InMemory/ngrok/redis pubsub configured).

Common situations: Registering the workflow with a plain Mastra instance (no eventing config) while using evented workflow APIs; running in a test that constructs the workflow standalone without mastra.__registerWorkflow; upgrading to evented workflow APIs without adding pubsub to the Mastra constructor.

Related errors

• No Pubsub adapter configured on the Mastra instance
• @mastra/livekit: `workflowInput` is required when `workflow`
• crossProcessPubSub requires a pubsub instance
• save-workflow requires a Mastra context.
• InProcessStrategy: could not resolve step "${params.stepId}"

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