{"record":{"id":"c69f44f76e9ec7d0","repo":"mastra-ai/mastra","slug":"mastra-instance-with-pubsub-is-required-for-workfl","errorCode":null,"errorMessage":"Mastra instance with pubsub is required for workflow execution","messagePattern":"Mastra instance with pubsub is required for workflow execution","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/workflows/evented/workflow.ts","lineNumber":1950,"sourceCode":"      requestContext: requestContext.toJSON(),\n      activePaths: [],\n      activeStepsPath: {},\n      suspendedPaths: {},\n      resumeLabels: {},\n      waitingPaths: {},\n      timestamp: Date.now(),\n    };\n    await workflowsStore?.persistWorkflowSnapshot({\n      workflowName: this.workflowId,\n      runId: this.runId,\n      resourceId: this.resourceId,\n      snapshot: this.executionEngine.options?.pruneSnapshot\n        ? this.executionEngine.options.pruneSnapshot({ snapshot: initialRunSnapshot, workflowStatus: 'running' })\n        : initialRunSnapshot,\n    });\n\n    if (!this.mastra?.pubsub) {\n      throw new Error('Mastra instance with pubsub is required for workflow execution');\n    }\n\n    this.setupAbortHandler();\n\n    // The evented engine runs steps from serialized pubsub events, which can't\n    // carry the non-serializable AISpan. Create the WORKFLOW_RUN span here and\n    // hold it on Mastra keyed by runId; the event processor nests each step's\n    // spans under it (see `WorkflowEventProcessor.resolveRunTracingContext`).\n    const workflowSpan = getOrCreateSpan({\n      type: SpanType.WORKFLOW_RUN,\n      name: `workflow run: '${this.workflowId}'`,\n      entityType: EntityType.WORKFLOW_RUN,\n      entityId: this.workflowId,\n      entityName: this.workflowId,\n      input: inputDataToUse,\n      metadata: { resourceId: this.resourceId, runId: this.runId },\n      tracingPolicy: this.tracingPolicy,\n      tracingContext,","sourceCodeStart":1932,"sourceCodeEnd":1968,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workflows/evented/workflow.ts#L1932-L1968","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pass an eventing config with a pubsub to the Mastra constructor: new Mastra({ ..., server: { experimentalIsEvented: true } }) or the pubsub option for your deployment","Register the workflow on the Mastra instance (mastra.addWorkflow(workflow)) so this.mastra is populated","Verify you are importing/using the evented workflow path intentionally; if you don't need eventing, use the standard workflow instead"],"exampleFix":"// before\nexport const mastra = new Mastra({ workflows: { myWorkflow } });\n// after\nexport const mastra = new Mastra({\n  workflows: { myWorkflow },\n  server: { experimentalIsEvented: true },\n});","handlingStrategy":"validation","validationCode":"if (!mastra.getPubsub?.() && !('pubsub' in mastra)) {\n  throw new Error('Mastra must be configured with pubsub for evented workflows');\n}","typeGuard":"function hasPubsub(mastra) {\n  return Boolean(mastra && 'pubsub' in mastra && mastra.pubsub);\n}","tryCatchPattern":"try {\n  await run.start({ inputData });\n} catch (e) {\n  if (e.message.includes('pubsub is required')) {\n    throw new Error('Configure eventing (pubsub) on your Mastra instance before using evented workflows', { cause: e });\n  }\n  throw e;\n}","preventionTips":["Register workflows on the Mastra instance so this.mastra is set","Enable the evented server/pubsub option when using evented workflow APIs","Add a startup assertion that mastra.pubsub exists in evented deployments"],"tags":["workflow","pubsub","configuration","evented"],"backgroundTag":"missing-pubsub-configuration","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}