mastra-ai/mastra · error

Tool "${toolId}" is not available in Code Mode

Error message

Tool "${toolId}" is not available in Code Mode

What it means

Inside Code Mode, generated code calls tools via the external_* dispatcher. The dispatcher looks the toolId up in the registered toolsById map and throws when the tool is missing or has no execute function, preventing the model-authored program from invoking tools that were never exposed to Code Mode.

Source

Thrown at packages/core/src/tools/code-mode/code-mode.ts:107

      let sandbox: WorkspaceSandbox | undefined = config.sandbox;
      if (!sandbox && transport.requiresSandbox !== false) {
        const requestContext = ctx?.requestContext ?? new RequestContext();
        sandbox = await ctx?.workspace?.resolveSandbox({ requestContext });
        if (!sandbox) {
          throw new Error(
            'Code Mode requires a sandbox to run model-authored code, but none was configured. ' +
              'Pass one to createCodeMode({ tools, sandbox }), or run the agent in a workspace that provides a sandbox. ' +
              'To execute on the host (host privileges — only for trusted/local use), pass `sandbox: new LocalSandbox()`.',
          );
        }
      }

      // Each external_* call re-enters the real Mastra tool pipeline (validation,
      // request-context checks, tracing) on the host, with the outer tool's context.
      const dispatch: CodeModeToolDispatcher = async (toolId, args) => {
        const tool = toolsById.get(toolId);
        if (!tool?.execute) {
          throw new Error(`Tool "${toolId}" is not available in Code Mode`);
        }
        const result = await tool.execute(args, {
          mastra: ctx?.mastra,
          requestContext: ctx?.requestContext,
          abortSignal: ctx?.abortSignal,
          workspace: ctx?.workspace,
        });
        if (isValidationError(result)) {
          throw new Error(result.message ?? `Invalid input for tool "${toolId}"`);
        }
        return result;
      };

      // The TypeScript program is written to a .ts module by the transport;
      // the sandbox's node strips the type annotations natively at import.
      return ctx.observe.span(`code-mode:${id}`, () =>
        transport.run({
          sandbox,

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Include the tool in the tools map passed to createCodeMode so it is registered in toolsById.
  2. Ensure the tool has an execute function; remove marker/placeholder tools from Code Mode's tool set.
  3. Tighten the tool descriptions/stubs so the model only calls registered tool ids.
  4. If the model fabricates names, constrain the prompt or validate the generated program before running.

Example fix

// before
const codeMode = createCodeMode({ tools: { weather } }); // model calls external_search
// after
const codeMode = createCodeMode({ tools: { weather, search } });
Defensive patterns

Strategy: try-catch

Validate before calling

const registered = new Set(Object.keys(tools));
// before running, ensure generated program only references registered ids:
const referenced = [...program.matchAll(/external_(\w+)/g)].map(m => m[1]);
const unknown = referenced.filter(n => !registered.has(n));
if (unknown.length) throw new Error(`Program references unregistered tools: ${unknown}`);

Try / catch

try {
  result = await codeModeTool.execute(args, ctx);
} catch (e) {
  if (String(e.message).includes('is not available in Code Mode')) {
    // regenerate with corrected tool list / re-prompt the model
  } else throw e;
}

Prevention

When it happens

Trigger: Model-generated code calls external_foo for a tool id that was not included in the tools map passed to createCodeMode, or the registered entry lacks an execute function (e.g. a placeholder/marker tool like webSearchTool).

Common situations: The model hallucinates or mistypes a tool name; the tool was filtered out of the Code Mode tool set but the model still saw its stub from a previous turn; passing non-executable tool placeholders into createCodeMode.

Related errors

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