{"record":{"id":"07bacb26d0d6195f","repo":"mastra-ai/mastra","slug":"orchestrationworker-requires-mastra-instance","errorCode":null,"errorMessage":"OrchestrationWorker requires Mastra instance","messagePattern":"OrchestrationWorker requires Mastra instance","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/worker/workers/orchestration-worker.ts","lineNumber":44,"sourceCode":"export class OrchestrationWorker extends MastraWorker {\n  readonly name = 'orchestration';\n\n  #config: OrchestrationWorkerConfig;\n  #transport?: WorkerTransport;\n  #processor?: WorkflowEventProcessor;\n  #strategy?: StepExecutionStrategy;\n  #running = false;\n\n  constructor(config: OrchestrationWorkerConfig = {}) {\n    super();\n    this.#config = config;\n  }\n\n  async init(deps: WorkerDeps): Promise<void> {\n    await super.init(deps);\n\n    if (!deps.mastra) {\n      throw new Error('OrchestrationWorker requires Mastra instance');\n    }\n\n    // OrchestrationWorker drives a pull subscription on the workflow topic.\n    // Push-only pubsubs (EventEmitter, GCP push subscriptions) deliver events\n    // through different paths and must not be paired with this worker.\n    const modes = deps.pubsub.supportedModes ?? ['pull'];\n    if (!modes.includes('pull')) {\n      throw new Error(\n        `OrchestrationWorker requires a pull-capable PubSub, but the configured pubsub only supports: ${modes.join(', ')}. ` +\n          `Either remove OrchestrationWorker from the workers list or use a pull-capable PubSub (e.g. Redis Streams).`,\n      );\n    }\n\n    // If MASTRA_STEP_EXECUTION_URL is set, use HttpRemoteStrategy\n    // (standalone worker calling back to the server for step execution).\n    // The strategy reads MASTRA_WORKER_AUTH_TOKEN itself and forwards it\n    // through the server's normal Mastra auth provider — there is no\n    // separate \"worker secret\" gate.","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/worker/workers/orchestration-worker.ts#L26-L62","documentation":"OrchestrationWorker needs the Mastra instance to resolve workflows, register its step-execution strategy, and process workflow events. init() validates deps.mastra and throws this error when it's absent, since a standalone orchestration worker cannot function without it.","triggerScenarios":"Calling init() with a WorkerDeps object that omits mastra (e.g. only { storage, logger, pubsub }).","commonSituations":"Reusing generic worker bootstrap code built for BackgroundTaskWorker (which doesn't require mastra) for OrchestrationWorker; building deps programmatically where mastra is optional-typed and left undefined.","solutions":["Pass the Mastra instance in deps: await worker.init({ ...deps, mastra })","Create the Mastra instance before initializing workers and confirm it isn't undefined due to async/conditional setup","Verify you aren't shadowing the mastra field (e.g. destructuring bug assigning undefined)"],"exampleFix":"// before\nawait orchestrationWorker.init({ storage, logger, pubsub });\n// after\nawait orchestrationWorker.init({ storage, logger, pubsub, mastra });","handlingStrategy":"validation","validationCode":"if (!deps.mastra) throw new Error('OrchestrationWorker init requires mastra');\nawait worker.init(deps);","typeGuard":"function hasMastra(d) { return !!d && !!d.mastra; }","tryCatchPattern":"try {\n  await worker.init(deps);\n} catch (e) {\n  if (e.message === 'OrchestrationWorker requires Mastra instance') {\n    throw new Error('Bootstrap bug: mastra missing from worker deps');\n  } else throw e;\n}","preventionTips":["Build deps from a single typed factory that always includes mastra","Enable strict TypeScript so optional mastra fields are flagged at call sites","Initialize Mastra before any worker wiring"],"tags":["worker","configuration","dependency-injection"],"backgroundTag":"missing-required-dependency","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}