mastra-ai/mastra · error · Error

Worker "${name}" not found. Available: ${this.#workers.map(w

Error message

Worker "${name}" not found. Available: ${this.#workers.map(w => w.name).join(', ')}

What it means

When starting/filtering workers, Mastra matches the requested name against registered MastraWorker instances. If no worker with that name is registered it throws a plain Error that helpfully lists the available worker names so the caller can self-correct.

Source

Thrown at packages/core/src/mastra/index.ts:6106

        const { AgentScheduleWorker } = await import('../schedules/worker');
        const asw = new AgentScheduleWorker();
        asw.__registerMastra(this);
        this.#workers.push(asw);
      }
    }

    const deps: WorkerDeps = {
      pubsub: this.#pubsub,
      storage: this.#storage!,
      logger: this.#logger as unknown as IMastraLogger,
      mastra: this,
    };

    let targets: MastraWorker[];
    if (name) {
      targets = this.#workers.filter(w => w.name === name);
      if (targets.length === 0) {
        throw new Error(`Worker "${name}" not found. Available: ${this.#workers.map(w => w.name).join(', ')}`);
      }
    } else if (this.#workerFilter) {
      targets = this.#workers.filter(w => this.#workerFilter!.has(w.name));
      if (targets.length === 0) {
        this.#logger?.warn?.(
          `MASTRA_WORKERS=${[...this.#workerFilter].join(',')} did not match any registered workers (have: ${this.#workers.map(w => w.name).join(', ')})`,
        );
      }
    } else {
      targets = this.#workers;
    }

    // Rehydrate persisted workflow definitions (after storage.init() above).
    if (this.#storage) {
      await this.#loadDynamicWorkflows();
    }

    // When explicitly starting the backgroundTasks worker (e.g.

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the 'Available:' list in the message and use one of those exact names.
2. Fix the name's spelling/casing to match the registration (strict equality on w.name).
3. Register the missing worker on this Mastra instance before starting it.
4. Update the MASTRA_WORKERS filter to reference currently registered worker names.

Example fix

// before
mastra.startWorkers('email-worker'); // registered as 'emailWorker'
// after
mastra.startWorkers('emailWorker');

const available = mastra.getWorkers?.().map(w => w.name) ?? [];
if (name && !available.includes(name)) {
  throw new Error(`Worker "${name}" not registered. Available: ${available.join(', ')}`);
}

try {
  mastra.startWorkers(name);
} catch (e) {
  if (e instanceof Error && e.message.includes('not found. Available:')) {
    console.warn(`Unknown worker "${name}"; starting all registered workers instead.`);
    mastra.startWorkers();
  } else throw e;
}

When it happens

Trigger: Calling the workers runner (e.g. startWorkers(name)) with a name that does not exactly equal any registered worker's name; the empty-string check means any truthy-but-unmatched name triggers this.

Common situations: Typo in the worker name; name case mismatch; the MASTRA_WORKERS env filter naming a worker that no longer exists; worker registered only in another Mastra instance/entrypoint.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Sandbox provider "${options.sandbox.provider}" does not supp
• terminationGraceMs must be greater than zero.
• Worker command must be a non-empty executable path.
• Worker arguments must not contain NUL bytes.
• Invalid worker environment variable name: ${key}

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