What causes "list-workflows requires a Mastra context." in mastra-ai/mastra?

Execute within a Mastra runtime so the context includes `mastra`.

list-workflows requires a Mastra context.

Error message

list-workflows requires a Mastra context.

What it means

list-workflows delegates to `listWorkflows(mastra)` (the storage-backed listing, including archived workflows) and requires a Mastra instance for storage access. It throws this Error when `mastra` is absent from the runtime context, because persisted workflow metadata cannot be read without it.

Source

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

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

export const listWorkflowsTool = createTool({
  id: 'list-workflows',
  description: 'List active Dynamic Workflows persisted to storage. Returns id + description + status for each.',
  inputSchema: z.object({}),
  outputSchema: z.object({
    workflows: z.array(
      z.object({
        id: z.string(),
        description: z.string().optional(),
        status: z.enum(['active', 'archived']),
      }),
    ),
    total: z.number(),
  }),
  execute: async (_input, { mastra }) => {
    if (!mastra) throw new Error('list-workflows requires a Mastra context.');
    const { workflows, total } = await listWorkflows(mastra as Mastra);
    return {
      workflows: workflows.map(wf => ({ id: wf.id, description: wf.description, status: wf.status })),
      total,
    };
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

Execute within a Mastra runtime so the context includes `mastra`.
For manual calls, pass `{ mastra }` in the second argument of execute.
Ensure the Mastra instance has storage configured, since this tool lists persisted workflows (active/archived).
In tests, initialize Mastra with storage (e.g. LibSQL/pg) and include it in the context.

Example fix

// before
await listWorkflowsTool.execute({ status: 'active' }, { requestContext });
// after
const mastra = new Mastra({ storage: new LibSQLStore({ url: 'file:./mastra.db' }) });
await listWorkflowsTool.execute({ status: 'active' }, { mastra, requestContext });

Defensive patterns

Strategy: try-catch

Validate before calling

if (!ctx?.mastra) {
  console.warn('Skipping list-workflows: no Mastra context (storage-backed listing unavailable).');
} else if (!ctx.mastra.getConfig?.()?.storage) {
  console.warn('Mastra instance has no storage; list-workflows may return nothing or fail.');
}

Type guard

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

Try / catch

try {
  const { workflows, total } = await listWorkflowsTool.execute({ status: 'active' }, ctx);
} catch (err) {
  if (err instanceof Error && err.message.includes('requires a Mastra context')) {
    // initialize Mastra with storage and re-invoke, or degrade gracefully
  } else throw err;
}

Prevention

Configure storage on the Mastra instance before listing persisted workflows.
Always pass the same Mastra instance that owns your workflows into the tool context.
In scripts/tests, bootstrap Mastra (with storage) before tool execution.
Wrap tool executions in a helper that validates context presence and logs actionable errors.

When it happens

Trigger: Executing list-workflows with an executionContext lacking `mastra` — manual execute calls, custom runners, or tests with partial context mocks. Unlike list-available-workflows this also needs Mastra's storage layer, so an instance without configured storage may fail downstream too.

Common situations: Invoking the tool outside Mastra's server/agent runtime; test scaffolds that stub `{ requestContext }` only; running the tool in scripts that construct tools without ever creating a Mastra instance.

Related errors

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