list-available-workflows requires a Mastra context.

Error message

list-available-workflows requires a Mastra context.

What it means

list-available-workflows reads workflow definitions via `mastra.listWorkflows()`. Its execute throws this Error when the runtime context does not contain a `mastra` instance, since there is no workflow registry to inspect. The guard ensures the tool only runs inside a Mastra-managed runtime.

Source

Thrown at mastracode/sdk/src/tools/workflows/list-available-workflows.ts:28

import { extractJsonSchema } from './extract-json-schema.js';

export const listAvailableWorkflowsTool = createTool({
  id: 'list-available-workflows',
  description:
    'Returns the workflows currently registered on the Mastra instance (both code-defined and dynamic). The ids returned here are the only valid values you can put in `{ type: "workflow", workflowId }` graph entries. Each row includes `inputSchema` and `outputSchema` as JSON Schema — read them to know what shape the nested workflow expects and produces; never invent field names.',
  inputSchema: z.object({}),
  outputSchema: z.object({
    workflows: z.array(
      z.object({
        id: z.string(),
        description: z.string().optional(),
        inputSchema: z.any().optional(),
        outputSchema: z.any().optional(),
      }),
    ),
  }),
  execute: async (_input, { mastra }) => {
    if (!mastra) throw new Error('list-available-workflows requires a Mastra context.');
    const all = (mastra as Mastra).listWorkflows?.() ?? {};
    return {
      workflows: Object.entries(all).map(([id, wf]) => {
        const w = wf as { description?: string; inputSchema?: unknown; outputSchema?: unknown } | undefined;
        return {
          id,
          description: w?.description,
          inputSchema: extractJsonSchema(w?.inputSchema, 'input'),
          outputSchema: extractJsonSchema(w?.outputSchema, 'output'),
        };
      }),
    };
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

Run the tool through a Mastra agent/server/Studio so `mastra` is present in the context.
When invoking manually, pass `{ mastra: new Mastra({ workflows: ... }) }` in the executionContext.
Register your workflows on the Mastra instance before executing the tool.
In tests, use a real Mastra instance in the context instead of an empty object.

Example fix

// before
await tool.execute({}, {} as any);
// after
const mastra = new Mastra({ workflows: { myWorkflow } });
await tool.execute({}, { mastra, requestContext });

Defensive patterns

Strategy: validation

Validate before calling

const ok =
  executionContext &&
  typeof executionContext === 'object' &&
  'mastra' in executionContext &&
  executionContext.mastra != null &&
  typeof executionContext.mastra.listWorkflows === 'function';
if (!ok) throw new Error('Provide a Mastra instance in the execution context.');

Type guard

function isMastraExecContext(ctx: unknown): ctx is { mastra: Mastra; requestContext?: RequestContext } {
  return (
    typeof ctx === 'object' &&
    ctx !== null &&
    'mastra' in ctx &&
    (ctx as any).mastra instanceof Mastra
  );
}

Try / catch

try {
  const { workflows } = await tool.execute(input, ctx);
} catch (err) {
  if (err instanceof Error && err.message === 'list-available-workflows requires a Mastra context.') {
    // inject a Mastra instance (with workflows registered) and retry
  } else throw err;
}

Prevention

Construct `new Mastra({ workflows: ... })` before executing workflow-related tools.
Never call tool.execute with an empty/partial context object in production code.
Centralize context creation (mastra + requestContext) in one helper.
Add an integration test asserting tools run with a fully-populated context.

When it happens

Trigger: Calling the tool's execute with a context object missing `mastra` — direct/manual invocation, non-Mastra harnesses, or test doubles without the Mastra instance.

Common situations: Embedding the SDK workflow tools in custom automation that bypasses Mastra's context injection; integration tests stubbing executionContext; invoking tools before Mastra is constructed (workflows not yet registered).

Related errors

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