{"record":{"id":"615f70c212c0f240","repo":"vercel/ai","slug":"tool-choice-type-type-functionality-not-supp-615f70","errorCode":null,"errorMessage":"'tool choice type: ${type}' functionality not supported.","messagePattern":"'tool choice type: (.+?)' functionality not supported\\.","errorType":"exception","errorClass":"UnsupportedFunctionalityError","httpStatus":null,"severity":"error","filePath":"packages/xai/src/xai-prepare-tools.ts","lineNumber":94,"sourceCode":"    case 'auto':\n    case 'none':\n      return { tools: xaiTools, toolChoice: type, toolWarnings };\n    case 'required':\n      // xai supports 'required' directly\n      return { tools: xaiTools, toolChoice: 'required', toolWarnings };\n    case 'tool':\n      // xai supports specific tool selection\n      return {\n        tools: xaiTools,\n        toolChoice: {\n          type: 'function',\n          function: { name: toolChoice.toolName },\n        },\n        toolWarnings,\n      };\n    default: {\n      const _exhaustiveCheck: never = type;\n      throw new UnsupportedFunctionalityError({\n        functionality: `tool choice type: ${_exhaustiveCheck}`,\n      });\n    }\n  }\n}\n","sourceCodeStart":76,"sourceCodeEnd":100,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/xai/src/xai-prepare-tools.ts#L76-L100","documentation":"prepareTools in the xAI provider validates the toolChoice argument against the exhaustive list of LanguageModelV4 tool choice types ('auto', 'none', 'required', 'tool'). The switch statement ends with a TypeScript exhaustiveness check (`const _exhaustiveCheck: never = type`), and throwing UnsupportedFunctionalityError means an unrecognized or unsupported tool choice type reached the provider. In practice this fires when a tool choice value outside the supported set is passed to generateText/streamText with an xAI model.","triggerScenarios":"Calling generateText/streamText with an xAI model and toolChoice set to a value that is not 'auto' | 'none' | 'required' | { type: 'tool', toolName } — e.g. a malformed object, an old provider-spec tool choice shape, or a raw string like 'any' from code written for another provider SDK.","commonSituations":"Porting code from OpenAI SDKs that use tool choice values like 'any' or 'function'; upgrading AI SDK versions and passing a stale toolChoice shape; hand-constructing toolChoice objects instead of using the union type; typos such as toolChoice: 'automatic'.","solutions":["Set toolChoice to one of the supported values: 'auto', 'none', 'required', or { type: 'tool', toolName: 'yourTool' }.","Remove the toolChoice argument entirely (defaults to auto behavior) if the desired mode is not supported.","Check for typos and that the value comes from the `ai` package types (ToolChoice), not another provider SDK.","If using a custom provider wrapper, verify the toolChoice passes through the correct LanguageModelV4 typing instead of an untyped string."],"exampleFix":"// before\nconst { text } = await generateText({ model: xai('grok-3'), tools, toolChoice: 'any' });\n\n// after\nconst { text } = await generateText({ model: xai('grok-3'), tools, toolChoice: 'required' });","handlingStrategy":"validation","validationCode":"const VALID = new Set(['auto', 'none', 'required']);\nfunction isValidToolChoice(tc: unknown): boolean {\n  return (\n    typeof tc === 'string' && VALID.has(tc) ||\n    (typeof tc === 'object' && tc !== null && (tc as any).type === 'tool' && typeof (tc as any).toolName === 'string')\n  );\n}\n// assert before the call: if (toolChoice !== undefined && !isValidToolChoice(toolChoice)) throw ...\n","typeGuard":"function isToolChoice(v: unknown): v is 'auto' | 'none' | 'required' | { type: 'tool'; toolName: string } {\n  return v === 'auto' || v === 'none' || v === 'required' ||\n    (typeof v === 'object' && v !== null && (v as any).type === 'tool' && typeof (v as any).toolName === 'string');\n}","tryCatchPattern":"try {\n  await generateText({ model: xai('grok-3'), tools, toolChoice });\n} catch (e) {\n  if (UnsupportedFunctionalityError.isInstance(e)) {\n    console.error('Unsupported toolChoice for xAI:', e.functionality);\n  } else throw e;\n}","preventionTips":["Always type toolChoice with the ToolChoice union from `ai` so invalid strings fail at compile time.","Do not copy toolChoice values from other provider SDKs (e.g. 'any', 'function').","Add a unit test that exercises each toolChoice mode against the xAI provider mock."],"tags":["xai","tool-choice","unsupported-functionality","configuration"],"backgroundTag":"unsupported-tool-choice","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}