mastra-ai/mastra · 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

When a workflow definition references an agent by string id, executeAgent resolves it via mastra.getAgentById at run time. If no agent instance was passed directly and the id is not registered on the Mastra instance, execution of the step throws this error.

Source

Thrown at packages/core/src/workflows/default.ts:1203

  async executeSleepUntil(params: ExecuteSleepUntilParams): Promise<void> {
    return executeSleepUntilHandler(this, params);
  }

  async executeStep(params: ExecuteStepParams): Promise<StepExecutionResult> {
    return executeStepHandler(this, params);
  }

  /**
   * Executes a declarative `agent` step: resolves the agent (live ref, else
   * `mastra.getAgentById(agentId)`), builds its runnable step, and runs it through
   * the shared step runner.
   */
  async executeAgent(params: ExecuteAgentParams): Promise<StepExecutionResult> {
    const { entry, ...rest } = params;
    const agent = entry.agent ?? this.mastra?.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.`,
      );
    }
    return this.executeStep({ ...rest, step: { ...createStepFromAgent(agent as any, entry.options), id: entry.id } });
  }

  /**
   * Executes a declarative `tool` step: resolves the tool (live ref, else
   * `mastra.getTool(toolId)`), builds its runnable step, and runs it through the
   * shared step runner.
   */
  async executeTool(params: ExecuteToolParams): Promise<StepExecutionResult> {
    const { entry, ...rest } = params;
    const tool = entry.tool ?? this.mastra?.getTool(entry.toolId);
    if (!tool) {
      throw new Error(
        `Tool '${entry.toolId}' not found for workflow step '${entry.id}'. Pass the tool instance directly.`,
      );

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register the agent on the Mastra instance: new Mastra({ agents: { myAgent } }).
2. Pass the agent instance directly in the step entry (`entry.agent`) instead of relying on agentId resolution.
3. Fix the agentId string to match the registered agent, and update any stored workflow definitions in the DB.

Example fix

// before
new Mastra({ workflows: { myWorkflow } }) // agent 'myAgent' never registered
// after
new Mastra({ agents: { myAgent: myAgent }, workflows: { myWorkflow } })

const agent = entry.agent ?? mastra.getAgentById?.(entry.agentId);
if (!agent) {
  throw new Error(`Agent '${entry.agentId}' is not registered on the Mastra instance before running the workflow`);
}

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

try {
  await workflow.start({ inputData });
} catch (e) {
  if (e instanceof Error && e.message.includes("not found for workflow step")) {
    // register the missing agent or fix agentId, then retry
  }
  throw e;
}

When it happens

Trigger: A dynamic/stored workflow graph entry `{ type: 'agent', agentId: 'myAgent' }` executes while: the agent was never registered via `new Mastra({ agents: { myAgent } })`, the id is misspelled, the agent was registered after workflow execution started, or the workflow runs without a Mastra instance attached.

Common situations: Renaming an agent without updating stored workflow definitions; deploying workflows to a service that registers a different agent set; running rehydrated workflows from storage against a fresh Mastra instance missing that agent; typo in agentId in a builder UI export.

Related errors

• RUN_EXPERIMENT_TARGET_FAILED_TO_GENERATE_RESULT
• Tool '${entry.toolId}' not found for workflow step '${entry.
• Dynamic workflow references agent "${entry.agentId}" which i
• Agent step "${params.id}" uses a legacy v1 model but does no
• Workflow ${workflowId} not found

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