mastra-ai/mastra · error

list-available-tools requires a Mastra context.

Error message

list-available-tools requires a Mastra context.

What it means

list-available-tools enumerates tools from the Mastra registry via `mastra.listTools()`. The execute function throws this Error when the injected runtime context has no `mastra` instance, because there is no registry to read tools from. It is a fail-fast guard against executing the tool outside a Mastra-managed runtime.

Source

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

const WORKFLOW_BUILDER_NOISE_TOOLS = new Set<string>(WORKFLOW_BUILDER_NOISE_TOOL_IDS);

export const listAvailableToolsTool = createTool({
  id: 'list-available-tools',
  description:
    'Returns the tools currently registered on the Mastra instance. The tool ids returned here are the only valid values you can put in `{ type: "tool", toolId }` graph entries. Each row includes `inputSchema` and `outputSchema` as JSON Schema — read them to know what fields the tool accepts and emits; never invent field names.',
  inputSchema: z.object({}),
  outputSchema: z.object({
    tools: 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-tools requires a Mastra context.');
    const all = (mastra as { listTools?: () => Record<string, unknown> }).listTools?.() ?? {};
    return {
      tools: Object.entries(all)
        .filter(([id]) => !WORKFLOW_BUILDER_NOISE_TOOLS.has(id))
        .map(([id, t]) => {
          const tool = t as { description?: string; inputSchema?: unknown; outputSchema?: unknown } | undefined;
          return {
            id,
            description: tool?.description,
            inputSchema: extractJsonSchema(tool?.inputSchema, 'input'),
            outputSchema: extractJsonSchema(tool?.outputSchema, 'output'),
          };
        }),
    };
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

1. Execute the tool within a Mastra runtime (agent, server, or Studio) so `mastra` is injected.
2. In custom code, supply `{ mastra }` in the executionContext when calling execute.
3. In tests, build a minimal `new Mastra({ ... })` and include it in the context.
4. Confirm the tool is registered with/derived from a Mastra instance rather than instantiated standalone.

Example fix

// before
const res = await listAvailableTools.execute({}, { requestContext });
// after
const mastra = new Mastra({ tools: { myTool } });
const res = await listAvailableTools.execute({}, { mastra, requestContext });

if (!executionContext?.mastra) {
  throw new Error('list-available-tools requires a Mastra context before execution.');
}

function hasMastra(ctx: unknown): ctx is { mastra: { listTools: () => Record<string, unknown> } } {
  return (
    typeof ctx === 'object' &&
    ctx !== null &&
    'mastra' in ctx &&
    typeof (ctx as any).mastra?.listTools === 'function'
  );
}

try {
  const { tools } = await listAvailableTools.execute(input, ctx);
} catch (err) {
  if (err instanceof Error && /requires a Mastra context/.test(err.message)) {
    // fall back to constructing/parsing a Mastra instance and retry once
  } else throw err;
}

When it happens

Trigger: Invoking list-available-tools' execute with an executionContext lacking `mastra` — manual `tool.execute()` calls, custom harnesses that don't inject Mastra, or test stubs omitting the runtime context.

Common situations: Custom workflow runners/bots invoking SDK tools directly without a Mastra server; test code with partial context mocks; calling the tool in an environment where the Mastra instance was never constructed or registered.

Related errors

• list-available-agents requires a Mastra context.
• list-available-workflows requires a Mastra context.
• list-workflows requires a Mastra context.
• run-workflow requires a Mastra context.
• save-workflow requires a Mastra context.

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