vercel/ai · error · UnsupportedFunctionalityError

'file part media type ${part.mediaType}' functionality not s

Error message

'file part media type ${part.mediaType}' functionality not supported.

What it means

For xAI file parts, only image media types are supported (mapped to image_url content). A file part with any other media type (e.g. application/pdf, audio) cannot be represented in xAI chat format and throws UnsupportedFunctionalityError naming the media type.

Source

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

                      provider: 'xai',
                      providerOptions: part.providerOptions,
                      schema: xaiFilePartProviderOptions,
                    });

                    userContent.push({
                      type: 'image_url',
                      image_url: {
                        url:
                          part.data.type === 'url'
                            ? part.data.url.toString()
                            : `data:${resolveFullMediaType({ part })};base64,${convertToBase64(part.data.data)}`,
                        ...(filePartOptions?.imageDetail != null && {
                          detail: filePartOptions.imageDetail,
                        }),
                      },
                    });
                  } else {
                    throw new UnsupportedFunctionalityError({
                      functionality: `file part media type ${part.mediaType}`,
                    });
                  }
                  break;
                }
              }
              break;
            }
          }
        }

        messages.push({ role: 'user', content: userContent });

        break;
      }

      case 'assistant': {
        let text = '';

View on GitHub (pinned to 69428b1f8b)

Solutions

Only send image file parts (image/*) to xAI models.
Inline non-image documents as text (extracted content) in a TextPart.
Use Grok's dedicated document/API surface or a provider that supports the media type.
Filter unsupported media types with a warning before the request.

Example fix

// before
content: [{ type: 'file', data: pdfBuffer, mediaType: 'application/pdf' }]
// after
content: [{ type: 'text', text: extractedPdfText }]

Defensive patterns

Strategy: validation

Validate before calling

function filterNonImageFileParts(messages: ModelMessage[]) {
  return messages.map(m => Array.isArray(m.content)
    ? { ...m, content: m.content.filter(p => !(p.type === 'file' && !p.mediaType.startsWith('image/'))) }
    : m);
}

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.startsWith('file part media type')) {
    return generateText({ model: xai('grok-4'), messages: filterNonImageFileParts(messages) });
  }
  throw e;
}

Prevention

Whitelist image/* media types in upload handling for xAI-backed chats.
Handle PDFs/audio via providers that support them or extract content to text first.
Check UnsupportedFunctionalityError.functionality in tests for each provider you target.

When it happens

Trigger: Passing a FilePart whose mediaType is not an image (e.g. 'application/pdf', 'audio/mpeg') to an @ai-sdk/xai model via generateText/streamText.

Common situations: Attaching PDFs or audio recordings to chat messages; multi-provider code paths assuming all providers accept documents; upload UIs forwarding arbitrary files to the model.

Related errors

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