mastra-ai/mastra · error

The "workflow-builder" sub-agent is not registered on this M

Error message

The "workflow-builder" sub-agent is not registered on this Mastra instance. Cannot build workflows.

What it means

create-workflow delegates to a sub-agent named 'workflow-builder' fetched via mastra.getAgent(). If no agent with that id is registered on the Mastra instance, this error is thrown. The library requires this sub-agent to exist to build and save workflows.

Source

Thrown at mastracode/sdk/src/tools/workflows/create-workflow.ts:44

  }
}

export const createWorkflowTool = createTool({
  id: 'create-workflow',
  description:
    'Build and save a Dynamic Workflow on behalf of the user. Pass the user request verbatim — a focused sub-agent handles discovery, construction, and persistence, then returns a summary. Use this whenever the user asks to "build a workflow", "compose a workflow", or similar. Do NOT try to construct workflows inline yourself.',
  inputSchema: z.object({
    request: z.string().describe('The user request, verbatim — do not paraphrase or summarise.'),
  }),
  outputSchema: z.object({
    summary: z.string().describe('Natural-language summary of what the sub-agent built. Relay this to the user.'),
    workflowId: z.string().optional().describe('The id of the saved workflow, if save-workflow returned ok.'),
  }),
  execute: async ({ request }, { mastra, requestContext }) => {
    if (!mastra) throw new Error('create-workflow requires a Mastra context.');
    const builder = (mastra as Mastra).getAgent('workflow-builder' as never);
    if (!builder) {
      throw new Error(
        'The "workflow-builder" sub-agent is not registered on this Mastra instance. Cannot build workflows.',
      );
    }

    // Propagate the parent code-agent's requestContext so the sub-agent's
    // dynamic model resolver (getDynamicModel) sees controller.session.modelId.
    // Without this the sub-agent throws "No model selected" even when the user
    // has /models configured for the main code-agent.
    const stream = await builder.stream(request, { requestContext });

    // Sub-agent runs its own tool loop. We MUST verify save-workflow actually
    // ran and returned ok — otherwise the sub-agent's natural-language "summary"
    // is worthless (it will happily claim success without ever calling the tool,
    // or claim success after save-workflow threw). Surface every error the
    // sub-agent's tools produce so the caller sees them instead of a fake ok.
    let workflowId: string | undefined;
    let saveAttempted = false;
    let saveSucceeded = false;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register the 'workflow-builder' agent on your Mastra instance: mastra.getAgent('workflow-builder') must resolve.
2. Check for typos/renames in the agent id in your mastra config.
3. Upgrade/align mastracode SDK setup so default agents are registered (follow the setup/init docs).

Example fix

// before
new Mastra({ agents: { 'code-agent': codeAgent } });
// after
new Mastra({ agents: { 'code-agent': codeAgent, 'workflow-builder': workflowBuilderAgent } });

const builder = mastra.getAgent('workflow-builder');
if (!builder) throw new Error('workflow-builder agent missing — register it before calling create-workflow');

function hasWorkflowBuilder(m: Mastra): boolean { try { return !!m.getAgent('workflow-builder'); } catch { return false; } }

try { const res = await tool.execute({ request }, { mastra }); } catch (e) { if (e.message.includes('workflow-builder')) { /* surface config error: agent not registered */ } else throw e; }

When it happens

Trigger: Calling create-workflow on a Mastra instance where getAgent('workflow-builder') returns undefined — the agent was never registered or was registered under a different id.

Common situations: Custom Mastra setups that omit the default workflow-builder agent; renaming the agent; partial migrations where only tools were copied over.

Related errors

• create-workflow requires a Mastra context.
• delete-workflow requires a Mastra context.
• get-workflow requires a Mastra context.
• @mastra/livekit: no workflow specified. Set `workflow` on cr
• create-workflow failed: save-workflow threw ${saveErrors.len

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