vercel/ai · error · UnsupportedFunctionalityError

'text file parts' functionality not supported.

Error message

'text file parts' functionality not supported.

What it means

convertToXaiChatMessages maps AI SDK file parts to xAI's chat format. xAI's chat API supports image file parts but not text file parts, so a file part with a text media type throws UnsupportedFunctionalityError with the message 'text file parts' functionality not supported.

Source

Thrown at packages/xai/src/convert-to-xai-chat-messages.ts:61

              userContent.push({ type: 'text', text: part.text });
              break;
            }
            case 'file': {
              switch (part.data.type) {
                case 'reference': {
                  userContent.push({
                    type: 'file',
                    file: {
                      file_id: resolveProviderReference({
                        reference: part.data.reference,
                        provider: 'xai',
                      }),
                    },
                  });
                  break;
                }
                case 'text': {
                  throw new UnsupportedFunctionalityError({
                    functionality: 'text file parts',
                  });
                }
                case 'url':
                case 'data': {
                  if (getTopLevelMediaType(part.mediaType) === 'image') {
                    const filePartOptions = await parseProviderOptions({
                      provider: 'xai',
                      providerOptions: part.providerOptions,
                      schema: xaiFilePartProviderOptions,
                    });

                    userContent.push({
                      type: 'image_url',
                      image_url: {
                        url:
                          part.data.type === 'url'
                            ? part.data.url.toString()

View on GitHub (pinned to 69428b1f8b)

Solutions

  1. Convert the text file content to a TextPart (inline the text into the prompt) before sending.
  2. If sending a document, use a provider that supports text file parts, or extract text yourself.
  3. Filter out text file parts with a warning before the call.

Example fix

// before
messages: [{ role: 'user', content: [{ type: 'file', data: txtBuffer, mediaType: 'text/plain' }] }]
// after
messages: [{ role: 'user', content: [{ type: 'text', text: txtBuffer.toString('utf-8') }] }]
Defensive patterns

Strategy: validation

Validate before calling

function assertNoTextFileParts(messages: ModelMessage[]) {
  for (const m of messages) {
    for (const p of Array.isArray(m.content) ? m.content : []) {
      if (p.type === 'file' && p.mediaType.startsWith('text/')) {
        throw new Error(`Convert text file part (${p.mediaType}) to a text part before sending to xAI`);
      }
    }
  }
}

Type guard

const isImageFilePart = (p: unknown): p is FilePart & { mediaType: `image/${string}` } =>
  typeof p === 'object' && p !== null && (p as any).type === 'file' &&
  String((p as any).mediaType).startsWith('image/');

Try / catch

try {
  await generateText({ model: xai('grok-4'), messages });
} catch (e) {
  if (UnsupportedFunctionalityError.isInstance(e) && e.functionality === 'text file parts') {
    messages = messages.map(convertTextFilePartsToText);
    return generateText({ model: xai('grok-4'), messages });
  }
  throw e;
}

Prevention

When it happens

Trigger: Passing a message containing a FilePart whose mediaType is a text type (e.g. text/plain) to a model from @ai-sdk/xai via generateText/streamText.

Common situations: Sending extracted PDF text or .txt/.csv attachments as file parts; generic file-upload UI forwarding all attachments to the model; code written for another provider (e.g. Anthropic, which supports text file parts) reused with xAI.

Related errors

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