ToolChoiceViolationError

This error occurs when a generateText or streamText response does not satisfy an enforced tool choice. It is thrown when toolChoice is set to 'none' but the response contains a tool call, when 'required' produces no structured tool call, or when a specifically selected tool was not called. With streamText, the error is emitted in the stream. Tool calls returned while 'none' is selected are not executed.

The error does not automatically interpret text or reasoning as an executable tool call. When tool calls are allowed, you can inspect content to implement opt-in recovery, including schema validation before executing any recovered call.

Properties

• toolChoice: The effective tool choice that the response did not satisfy
• finishReason: The reason why the model finished generating the response
• provider: The provider that returned the response
• modelId: The model that returned the response
• content: The normalized content returned by the model
• message: The error message

Checking for this Error

You can check if an error is an instance of ToolChoiceViolationError using:

import { ToolChoiceViolationError } from 'ai';

if (
  ToolChoiceViolationError.isInstance(error) &&
  error.toolChoice.type !== 'none'
) {
  const serializedCall = error.content.find(part => part.type === 'text')?.text;

  // Parse and validate serializedCall before treating it as a tool call.
}