vercel/ai · error · CodeModeToolError

CODE_MODE_TOOL_ERROR

CODE_MODE_TOOL_ERROR

Error message

Unknown tool: ${toolName}

What it means

invokeHostTool throws CodeModeToolError when the sandboxed code calls a tool name that is not present in the provided tools set. The error data includes `toolName` and `availableTools` so the developer can see what was requested versus what was registered. The code cannot proceed because there is no implementation to invoke.

Source

Thrown at packages/code-mode/src/tool-invocation.ts:59

  codeModeInterrupt,
  skipApproval = false,
}: {
  toolName: string;
  inputJson: string;
  tools: CodeModeToolSet;
  baseExecutionOptions: CodeModeToolExecutionOptions;
  codeModeOptions: CodeModeOptions;
  maxToolInputBytes: number;
  maxToolOutputBytes: number;
  toolCallId: string;
  codeModeInterrupt?: CodeModeInterruptExecutionContext;
  skipApproval?: boolean;
}): Promise<HostToolInvocationResult> {
  throwIfAborted(baseExecutionOptions.abortSignal);

  const hostTool = tools[toolName];
  if (!hostTool) {
    throw new CodeModeToolError(`Unknown tool: ${toolName}`, {
      toolName,
      availableTools: Object.keys(tools),
    });
  }
  if (hostTool.execute == null) {
    throw new CodeModeToolError(`Tool "${toolName}" does not have execute().`, {
      toolName,
    });
  }

  const input = fromJsonPayload(inputJson);
  assertJsonSerializable(input, maxToolInputBytes, `Tool "${toolName}" input`);

  const validation = await raceAgainstAbort(
    validateToolInput(hostTool.inputSchema, input),
    baseExecutionOptions.abortSignal,
  );
  if (!validation.success) {

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Add the missing tool to the tools object passed to runCodeMode.
2. Regenerate or correct the code so it only calls registered tools (list available tools in the code-generation prompt).
3. Check the error's `availableTools` data to confirm the exact registered names and fix typos.
4. If tools are intentionally filtered, instruct the model not to reference filtered tools or provide safe stubs.

Example fix

// before
await runCodeMode({ js, tools: { search } }); // code calls get_weather
// after
await runCodeMode({ js, tools: { search, get_weather: weatherTool } });

if (!(toolName in tools)) throw new Error(`Tool not registered: ${toolName}; available: ${Object.keys(tools).join(', ')}`);

function isRegisteredTool(name: string, tools: Record<string, unknown>): name is keyof typeof tools & string {
  return Object.prototype.hasOwnProperty.call(tools, name);
}

try {
  return await runCodeMode({ js, tools });
} catch (e) {
  if (CodeModeToolError.isInstance(e) && /^Unknown tool: /.test(e.message)) {
    // feed availableTools back to the model and let it regenerate the code
    return regenerateWithHints(e.data.availableTools);
  }
  throw e;
}

When it happens

Trigger: Generated code calls a helper like `get_weather(...)` that was not included in the `tools` passed to runCodeMode; a typo in the tool name inside the generated code; tools stripped by a policy filter.

Common situations: The model generated code referencing a tool it was told about in a prompt but that was never registered; tool set narrowed by permissions/approval filters; renaming a tool without regenerating the code.

Related errors

• error.message
• CODE_MODE_HOST_TOOL_ERROR
• Invalid argument for parameter batch: batch must be a suppor
• Sandbox session is not available
• Sandbox session is not available

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/aa73559619890527. Report an issue: GitHub.