{"record":{"id":"7c56747480d52dc1","repo":"mastra-ai/mastra","slug":"create-workflow-requires-a-mastra-context","errorCode":null,"errorMessage":"create-workflow requires a Mastra context.","messagePattern":"create-workflow requires a Mastra context\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/sdk/src/tools/workflows/create-workflow.ts","lineNumber":41,"sourceCode":"    return JSON.stringify(err) ?? String(err);\n  } catch {\n    return String(err);\n  }\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.","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/tools/workflows/create-workflow.ts#L23-L59","documentation":"create-workflow's execute needs the Mastra instance (passed via the tool execution context) to look up the workflow-builder agent. If the context object has no mastra instance, this error is thrown immediately. It indicates the tool is being executed outside a properly initialized Mastra runtime.","triggerScenarios":"Invoking the create-workflow tool with an execution context where { mastra } is undefined — e.g. calling execute directly without a server/runtime context.","commonSituations":"Unit-testing the tool with a stub context missing mastra; running the tool outside the Mastra server; constructing the tool config manually.","solutions":["Run the tool through the Mastra server/runtime so the execution context includes mastra.","In tests, pass a context with a real or mocked Mastra instance ({ mastra: mastraInstance }).","Register the tool on the Mastra instance rather than invoking its execute() standalone."],"exampleFix":"// before\nawait createWorkflowTool.execute({ request }, {} as any);\n// after\nawait createWorkflowTool.execute({ request }, { mastra, requestContext });","handlingStrategy":"try-catch","validationCode":"if (!mastra) throw new Error('create-workflow invoked without a Mastra instance');","typeGuard":"function hasMastraContext(ctx: unknown): ctx is { mastra: Mastra } { return !!ctx && typeof ctx === 'object' && 'mastra' in ctx && ctx.mastra != null; }","tryCatchPattern":"try { await tool.execute(args, { mastra, requestContext }); } catch (e) { if (e.message.includes('requires a Mastra context')) { /* re-run inside Mastra runtime */ } else throw e; }","preventionTips":["Always invoke tools through the Mastra server/runtime.","Never call tool.execute() directly with hand-built contexts in production code.","In tests, share a fixture that constructs a real Mastra instance."],"tags":["mastra-context","misconfiguration","workflows"],"backgroundTag":"missing-mastra-context","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}