mastra-ai/mastra · error · Error

Agent '${entry.agentId}' not found for workflow step '${entr

Error message

Agent '${entry.agentId}' not found for workflow step '${entry.id}'. Register the agent on the Mastra instance or pass the agent instance directly.

What it means

A workflow step references an agent by agentId, but neither an agent instance on the step entry nor an agent registered under that id on the Mastra instance could be resolved at execution time. runAgentEntry throws this Error before running the step because it cannot obtain the Agent to invoke.

Source

Thrown at packages/core/src/workflows/entry-executors/run-agent-entry.ts:29

import type { EntryExecuteContext } from './types';

/**
 * Runs a declarative `agent` entry: resolves the agent (inline handle, else the
 * Mastra registry), streams the prompt through it, forwards stream chunks, and
 * returns either the structured output or `{ text }`.
 *
 * `ctx` is the step execute context (the same object a plain step's `execute`
 * receives). `mastra` defaults to `ctx.mastra` when omitted.
 */
export async function runAgentEntry(
  entry: AgentStepEntry,
  ctx: EntryExecuteContext,
  mastra?: Mastra,
): Promise<unknown> {
  const registry = mastra ?? (ctx?.mastra as Mastra | undefined);
  const agent = entry.agent ?? registry?.getAgentById(entry.agentId);
  if (!agent) {
    throw new Error(
      `Agent '${entry.agentId}' not found for workflow step '${entry.id}'. Register the agent on the Mastra instance or pass the agent instance directly.`,
    );
  }

  // `retries` / `scorers` / `metadata` are step-level concerns handled by the
  // engine (see getEntryRetries); everything else is passed to the agent run.
  const { retries: _retries, scorers: _scorers, metadata: _metadata, ...agentOptions } = (entry.options ?? {}) as any;

  const {
    inputData,
    runId,
    [PUBSUB_SYMBOL]: pubsub,
    [STREAM_FORMAT_SYMBOL]: streamFormat,
    requestContext,
    actor,
    abortSignal,
    abort,
    writer,

View on GitHub (pinned to 75dd419e61)

Solutions

Register the agent on the Mastra instance: new Mastra({ agents: { myAgentId: myAgent } }) so getAgentById can find it.
Or pass the agent instance directly on the step entry: { id: 'step', agent: myAgent } instead of only agentId.
Verify the agentId string exactly matches the registration key (check for typos/casing).
Ensure the Mastra instance is available to the workflow engine (pass it as the mastra param or attach ctx.mastra).

Example fix

// before
steps: [{ id: 'summarize', agentId: 'summarizer' }] // 'summarizer' never registered
// after
new Mastra({ agents: { summarizer: new Agent({ name: 'summarizer', ... }) }) }
// or: steps: [{ id: 'summarize', agent: summarizerAgent }]

Defensive patterns

Strategy: validation

Validate before calling

const agent = entry.agent ?? mastra?.getAgentById(entry.agentId);
if (!agent) throw new Error(`Step '${entry.id}' references unregistered agent '${entry.agentId}'`);

Type guard

function hasAgent(entry: { agent?: unknown; agentId: string }, mastra?: Mastra): boolean {
  return !!entry.agent || !!mastra?.getAgentById(entry.agentId);
}

Try / catch

try { await runAgentEntry(entry, ctx, mastra); } catch (e) { if (e instanceof Error && e.message.includes("not found for workflow step")) { registerMissingAgent(entry.agentId); } else throw e; }

Prevention

Register every referenced agent on the Mastra instance at startup.
Prefer passing agent instances directly on step entries for dynamic workflows.
Keep agent ids in a shared constants module to avoid typos.
Assert all workflow agent references resolve before running (dry validation).

When it happens

Trigger: Executing a (dynamic) workflow whose step entry has agentId set but entry.agent undefined, while mastra.getAgentById(entry.agentId) returns undefined — i.e. the agent was never registered on the Mastra instance (or ctx.mastra is missing).

Common situations: Dynamic workflows created by codegen/LLM referencing agent ids that were never registered; agent registered with a different id/key than referenced; running the workflow engine without passing the Mastra instance (mastra argument and ctx.mastra both undefined); typos in agentId after renaming agents.

Related errors

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