{"record":{"id":"ee82d3bea3e3ff6a","repo":"mastra-ai/mastra","slug":"the-workflow-builder-sub-agent-is-not-registered","errorCode":null,"errorMessage":"The \"workflow-builder\" sub-agent is not registered on this Mastra instance. Cannot build workflows.","messagePattern":"The \"workflow-builder\" sub-agent is not registered on this Mastra instance\\. Cannot build workflows\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/sdk/src/tools/workflows/create-workflow.ts","lineNumber":44,"sourceCode":"  }\n}\n\nexport const createWorkflowTool = createTool({\n  id: 'create-workflow',\n  description:\n    '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.',\n  inputSchema: z.object({\n    request: z.string().describe('The user request, verbatim — do not paraphrase or summarise.'),\n  }),\n  outputSchema: z.object({\n    summary: z.string().describe('Natural-language summary of what the sub-agent built. Relay this to the user.'),\n    workflowId: z.string().optional().describe('The id of the saved workflow, if save-workflow returned ok.'),\n  }),\n  execute: async ({ request }, { mastra, requestContext }) => {\n    if (!mastra) throw new Error('create-workflow requires a Mastra context.');\n    const builder = (mastra as Mastra).getAgent('workflow-builder' as never);\n    if (!builder) {\n      throw new Error(\n        'The \"workflow-builder\" sub-agent is not registered on this Mastra instance. Cannot build workflows.',\n      );\n    }\n\n    // Propagate the parent code-agent's requestContext so the sub-agent's\n    // dynamic model resolver (getDynamicModel) sees controller.session.modelId.\n    // Without this the sub-agent throws \"No model selected\" even when the user\n    // has /models configured for the main code-agent.\n    const stream = await builder.stream(request, { requestContext });\n\n    // Sub-agent runs its own tool loop. We MUST verify save-workflow actually\n    // ran and returned ok — otherwise the sub-agent's natural-language \"summary\"\n    // is worthless (it will happily claim success without ever calling the tool,\n    // or claim success after save-workflow threw). Surface every error the\n    // sub-agent's tools produce so the caller sees them instead of a fake ok.\n    let workflowId: string | undefined;\n    let saveAttempted = false;\n    let saveSucceeded = false;","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/tools/workflows/create-workflow.ts#L26-L62","documentation":"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.","triggerScenarios":"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.","commonSituations":"Custom Mastra setups that omit the default workflow-builder agent; renaming the agent; partial migrations where only tools were copied over.","solutions":["Register the 'workflow-builder' agent on your Mastra instance: mastra.getAgent('workflow-builder') must resolve.","Check for typos/renames in the agent id in your mastra config.","Upgrade/align mastracode SDK setup so default agents are registered (follow the setup/init docs)."],"exampleFix":"// before\nnew Mastra({ agents: { 'code-agent': codeAgent } });\n// after\nnew Mastra({ agents: { 'code-agent': codeAgent, 'workflow-builder': workflowBuilderAgent } });","handlingStrategy":"validation","validationCode":"const builder = mastra.getAgent('workflow-builder');\nif (!builder) throw new Error('workflow-builder agent missing — register it before calling create-workflow');","typeGuard":"function hasWorkflowBuilder(m: Mastra): boolean { try { return !!m.getAgent('workflow-builder'); } catch { return false; } }","tryCatchPattern":"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; }","preventionTips":["Register the 'workflow-builder' agent in your Mastra constructor.","Assert agent registration at startup (fail fast on boot, not at tool call).","Avoid renaming default agent ids when customizing."],"tags":["mastra-context","agent-registration","workflows"],"backgroundTag":"agent-not-registered","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}