{"record":{"id":"12e8779ce57fa898","repo":"vercel/ai","slug":"unsupported-role-role","errorCode":null,"errorMessage":"Unsupported role: ${role}","messagePattern":"Unsupported role: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/xai/src/convert-to-xai-chat-messages.ts","lineNumber":175,"sourceCode":"            case 'content':\n            case 'json':\n            case 'error-json':\n              contentValue = JSON.stringify(output.value);\n              break;\n          }\n\n          messages.push({\n            role: 'tool',\n            tool_call_id: toolResponse.toolCallId,\n            content: contentValue,\n          });\n        }\n        break;\n      }\n\n      default: {\n        const _exhaustiveCheck: never = role;\n        throw new Error(`Unsupported role: ${_exhaustiveCheck}`);\n      }\n    }\n  }\n\n  return { messages, warnings };\n}\n","sourceCodeStart":157,"sourceCodeEnd":182,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/xai/src/convert-to-xai-chat-messages.ts#L157-L182","documentation":"convertToXaiChatMessages maps LanguageModelV4Prompt roles (system/user/assistant/tool) to xAI chat messages. The default branch is an exhaustiveness guard: it fires when a prompt contains a role the xAI chat adapter does not recognize, meaning the SDK's internal prompt and the provider adapter are out of sync (e.g. a newer role added to the spec without xAI support, or a corrupted prompt passed in by custom code).","triggerScenarios":"Passing a LanguageModelV4Prompt containing a role outside system/user/assistant/tool to streamText/generateText with an xai(...) chat model — practically only reachable via SDK version mismatch, monkey-patched prompts, or custom pipeline code building prompts manually.","commonSituations":"Mixing @ai-sdk/provider spec versions (e.g. a prompt built for LanguageModelV2 with roles like 'tool-result' differences) fed to the v4-based xAI provider; custom middleware injecting unsupported role objects.","solutions":["Upgrade @ai-sdk/xai and ai to matching latest versions so prompt roles and adapter support align","Check any custom prompt-building/middleware code for roles the xAI chat model does not support","Remove or convert unsupported roles (e.g. merge tool messages) before sending to xAI"],"exampleFix":"// before (custom prompt construction)\nconst prompt = [{ role: 'developer' as any, content: [{ type: 'text', text: 'hi' }] }];\n// after\nconst prompt = [{ role: 'system', content: [{ type: 'text', text: 'hi' }] }];","handlingStrategy":"type-guard","validationCode":"const supported = new Set(['system','user','assistant','tool']);\nif (!prompt.every(m => supported.has(m.role))) throw new Error('prompt has roles unsupported by xai chat model');","typeGuard":"function hasSupportedRoles(prompt: LanguageModelV4Prompt): boolean {\n  const ok = new Set(['system', 'user', 'assistant', 'tool'] as const);\n  return prompt.every(m => ok.has(m.role as 'system'));\n}","tryCatchPattern":"try {\n  await generateText({ model: xai('grok-4'), prompt });\n} catch (e) {\n  if ((e as Error).message.startsWith('Unsupported role:')) {\n    // rebuild/re-map the prompt before retrying\n  }\n}","preventionTips":["Keep ai and @ai-sdk/xai versions in lockstep","Avoid hand-constructing LanguageModelV4Prompt objects","Validate prompts in middleware before they reach the provider"],"tags":["xai","unsupported-role","exhaustiveness"],"backgroundTag":"unsupported-role","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}