What causes "get-workflow requires a Mastra context." in mastra-ai/mastra?

Run the tool through the Mastra runtime so mastra is injected into the context.

get-workflow requires a Mastra context.

Error message

get-workflow requires a Mastra context.

What it means

get-workflow's execute needs the Mastra instance from the execution context to load the workflow definition. If mastra is undefined, this error is thrown before the storage lookup. It means the tool ran outside a properly initialized Mastra runtime.

Source

Thrown at mastracode/sdk/src/tools/workflows/get-workflow.ts:24

import { z } from 'zod';
import { getWorkflow } from '../../workflows/service.js';

export const getWorkflowTool = createTool({
  id: 'get-workflow',
  description: 'Return the full stored definition of a workflow (input/output schemas + the step graph).',
  inputSchema: z.object({
    id: z.string().describe('The workflow id.'),
  }),
  outputSchema: z.object({
    id: z.string(),
    description: z.string().optional(),
    status: z.enum(['active', 'archived']),
    inputSchema: z.any().optional(),
    outputSchema: z.any().optional(),
    graph: z.array(z.any()).optional(),
  }),
  execute: async ({ id }, { mastra }) => {
    if (!mastra) throw new Error('get-workflow requires a Mastra context.');
    const def = await getWorkflow(mastra as Mastra, id);
    if (!def) throw new Error(`No workflow with id "${id}".`);
    return {
      id: def.id,
      description: def.description,
      status: def.status,
      inputSchema: def.inputSchema,
      outputSchema: def.outputSchema,
      graph: def.graph,
    };
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

Run the tool through the Mastra runtime so mastra is injected into the context.
In tests, supply { mastra: mastraInstance } as the execution context.
Ensure the tool is registered on and fetched from the Mastra instance.

Example fix

// before
await getWorkflowTool.execute({ id }, {} as any);
// after
await getWorkflowTool.execute({ id }, { mastra });

Defensive patterns

Strategy: try-catch

Validate before calling

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

Type guard

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

Try / catch

try { const def = await tool.execute({ id }, { mastra }); } catch (e) { if (e.message.includes('requires a Mastra context')) { /* re-run inside the Mastra runtime */ } else throw e; }

Prevention

Register the tool on the Mastra instance and call it via the runtime.
Use a shared test fixture providing { mastra } contexts.
Avoid ad-hoc execute() calls in scripts.

When it happens

Trigger: Calling get-workflow with an execution context where { mastra } is undefined — direct execute() invocation or non-Mastra runner.

Common situations: Unit tests with incomplete contexts; standalone scripts calling tool.execute(); tool consumed outside the Mastra server.

Related errors

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