mastra-ai/mastra · error · Error

AgentScheduleWorker requires Mastra instance

Error message

AgentScheduleWorker requires Mastra instance

What it means

AgentScheduleWorker.init() requires a Mastra instance in its WorkerDeps; it throws a plain Error when deps.mastra is missing. Unlike other workers, the agent schedule worker depends on the Mastra instance to execute agent schedules.

Source

Thrown at packages/core/src/schedules/worker.ts:66

 */
export class AgentScheduleWorker extends MastraWorker {
  readonly name = 'agent-schedule';

  #config: AgentScheduleWorkerConfig;
  #transport?: WorkerTransport;
  #pushCb?: EventCallback;
  #running = false;

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

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

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

  async start(): Promise<void> {
    if (this.#running) return;
    if (!this.deps) throw new Error('AgentScheduleWorker: call init() before start()');

    // Push-only pubsubs (EventEmitter, UnixSocketPubSub) don't support the
    // grouped pull subscription a PullTransport requires. They deliver every
    // event to every in-process subscriber, so subscribe directly without a
    // group — mirroring how Mastra.startWorkers handles workflow events for
    // push-only transports instead of running the pull-based worker.
    const modes = this.deps.pubsub.supportedModes ?? ['pull'];
    if (!modes.includes('pull')) {
      const cb: EventCallback = (event, ack, nack) => {
        void this.#handleEvent(event, ack, nack);
      };
      this.#pushCb = cb;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass the Mastra instance in deps: worker.init({ ...deps, mastra }).
2. Construct the worker after your Mastra instance exists and inject it directly.
3. If using a framework helper (e.g. Mastra.startWorkers), let it provide deps instead of manual init.

Example fix

// before
worker.init({ pubsub, storage });
// after
worker.init({ pubsub, storage, mastra });

if (!deps.mastra) throw new Error('AgentScheduleWorker: deps.mastra required');
await worker.init(deps);

function hasMastra(deps: Partial<WorkerDeps>): deps is WorkerDeps & { mastra: Mastra } {
  return Boolean(deps.mastra);
}

try {
  await worker.init(deps);
} catch (e) {
  if (String((e as Error).message).includes('requires Mastra')) {
    throw new Error('Worker bootstrap misconfigured: pass mastra in deps');
  }
  throw e;
}

When it happens

Trigger: Calling worker.init(deps) with a deps object whose mastra property is undefined/null.

Common situations: Manually wiring workers in a custom server setup and forgetting the mastra field; constructing deps programmatically where mastra is attached later; partial dependency injection after refactors.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• IssueReconcileWorker: call init() before start()
• AgentScheduleWorker: call init() before start()
• InProcessStrategy requires Mastra instance. Call __registerM
• BackgroundTaskWorker: call init() before start()
• BackgroundTaskWorker: failed to initialize background task m

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