mastra-ai/mastra · error

OrchestrationWorker requires Mastra instance

Error message

OrchestrationWorker requires Mastra instance

What it means

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.

Source

Thrown at packages/core/src/worker/workers/orchestration-worker.ts:44

export class OrchestrationWorker extends MastraWorker {
  readonly name = 'orchestration';

  #config: OrchestrationWorkerConfig;
  #transport?: WorkerTransport;
  #processor?: WorkflowEventProcessor;
  #strategy?: StepExecutionStrategy;
  #running = false;

  constructor(config: OrchestrationWorkerConfig = {}) {
    super();
    this.#config = config;
  }

  async init(deps: WorkerDeps): Promise<void> {
    await super.init(deps);

    if (!deps.mastra) {
      throw new Error('OrchestrationWorker requires Mastra instance');
    }

    // OrchestrationWorker drives a pull subscription on the workflow topic.
    // Push-only pubsubs (EventEmitter, GCP push subscriptions) deliver events
    // through different paths and must not be paired with this worker.
    const modes = deps.pubsub.supportedModes ?? ['pull'];
    if (!modes.includes('pull')) {
      throw new Error(
        `OrchestrationWorker requires a pull-capable PubSub, but the configured pubsub only supports: ${modes.join(', ')}. ` +
          `Either remove OrchestrationWorker from the workers list or use a pull-capable PubSub (e.g. Redis Streams).`,
      );
    }

    // If MASTRA_STEP_EXECUTION_URL is set, use HttpRemoteStrategy
    // (standalone worker calling back to the server for step execution).
    // The strategy reads MASTRA_WORKER_AUTH_TOKEN itself and forwards it
    // through the server's normal Mastra auth provider — there is no
    // separate "worker secret" gate.

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass the Mastra instance in deps: await worker.init({ ...deps, mastra })
2. Create the Mastra instance before initializing workers and confirm it isn't undefined due to async/conditional setup
3. Verify you aren't shadowing the mastra field (e.g. destructuring bug assigning undefined)

Example fix

// before
await orchestrationWorker.init({ storage, logger, pubsub });
// after
await orchestrationWorker.init({ storage, logger, pubsub, mastra });

if (!deps.mastra) throw new Error('OrchestrationWorker init requires mastra');
await worker.init(deps);

function hasMastra(d) { return !!d && !!d.mastra; }

try {
  await worker.init(deps);
} catch (e) {
  if (e.message === 'OrchestrationWorker requires Mastra instance') {
    throw new Error('Bootstrap bug: mastra missing from worker deps');
  } else throw e;
}

When it happens

Trigger: Calling init() with a WorkerDeps object that omits mastra (e.g. only { storage, logger, pubsub }).

Common situations: 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.

Related errors

• terminationGraceMs must be greater than zero.
• Worker command must be a non-empty executable path.
• ${name} must be greater than zero.
• Unknown worker resource limit: ${name}.
• @mastra/livekit: set exactly one reply generator — `generate

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