mastra-ai/mastra · error

create-workflow requires a Mastra context.

Error message

create-workflow requires a Mastra context.

What it means

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.

Source

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

    return JSON.stringify(err) ?? String(err);
  } catch {
    return String(err);
  }
}

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.

View on GitHub (pinned to 75dd419e61)

Solutions

1. Run the tool through the Mastra server/runtime so the execution context includes mastra.
2. In tests, pass a context with a real or mocked Mastra instance ({ mastra: mastraInstance }).
3. Register the tool on the Mastra instance rather than invoking its execute() standalone.

Example fix

// before
await createWorkflowTool.execute({ request }, {} as any);
// after
await createWorkflowTool.execute({ request }, { mastra, requestContext });

if (!mastra) throw new Error('create-workflow invoked without a Mastra instance');

function hasMastraContext(ctx: unknown): ctx is { mastra: Mastra } { return !!ctx && typeof ctx === 'object' && 'mastra' in ctx && ctx.mastra != null; }

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; }

When it happens

Trigger: Invoking the create-workflow tool with an execution context where { mastra } is undefined — e.g. calling execute directly without a server/runtime context.

Common situations: Unit-testing the tool with a stub context missing mastra; running the tool outside the Mastra server; constructing the tool config manually.

Related errors

• delete-workflow requires a Mastra context.
• get-workflow requires a Mastra context.
• The "workflow-builder" sub-agent is not registered on this M
• stagehand_close requires agent.threadId when browser scope i
• @mastra/livekit: no workflow specified. Set `workflow` on cr

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