What causes "file parts with provider references" in vercel/ai?

Replace the reference with a url or base64 data file part.

vercel/ai · error · UnsupportedFunctionalityError

file parts with provider references

Error message

file parts with provider references

What it means

Mistral chat models cannot consume file parts that reference files stored with a provider (provider references). convertToMistralChatMessages throws UnsupportedFunctionalityError when it encounters a 'file' part with data.type === 'reference'.

Source

Thrown at packages/mistral/src/convert-to-mistral-chat-messages.ts:57

    switch (role) {
      case 'system': {
        messages.push({ role: 'system', content });
        break;
      }

      case 'user': {
        messages.push({
          role: 'user',
          content: content.map(part => {
            switch (part.type) {
              case 'text': {
                return { type: 'text', text: part.text };
              }

              case 'file': {
                switch (part.data.type) {
                  case 'reference': {
                    throw new UnsupportedFunctionalityError({
                      functionality: 'file parts with provider references',
                    });
                  }
                  case 'text': {
                    throw new UnsupportedFunctionalityError({
                      functionality: 'text file parts',
                    });
                  }
                  case 'url':
                  case 'data': {
                    const topLevel = getTopLevelMediaType(part.mediaType);

                    if (topLevel === 'image') {
                      return {
                        type: 'image_url',
                        image_url: formatFileUrl({ part }),
                      };
                    } else {

View on GitHub (pinned to 69428b1f8b)

Solutions

Replace the reference with a url or base64 data file part.
Fetch the referenced file content yourself and pass it as binary data.
Strip reference-type file parts when targeting Mistral.
Use a provider that supports file references (e.g. OpenAI) for this request.

Example fix

// before
{ type: 'file', data: { type: 'reference', fileId: 'file-123' } }
// after
{ type: 'file', mediaType: 'application/pdf', data: { type: 'url', url: 'https://example.com/doc.pdf' } }

Defensive patterns

Strategy: validation

Validate before calling

function usesProviderFileReference(messages: { content: unknown[] }[]): boolean {
  return messages.some(m => (m.content as any[]).some(
    p => p?.type === 'file' && p?.data?.type === 'reference'));
}
if (usesProviderFileReference(messages)) throw new Error('References unsupported by Mistral');

Type guard

function isFileReferencePart(part: unknown): part is { type: 'file'; data: { type: 'reference'; fileId: string } } {
  return typeof part === 'object' && part !== null &&
    (part as any).type === 'file' &&
    (part as any).data?.type === 'reference';
}

Try / catch

try {
  await streamText({ model: mistral(modelId), messages });
} catch (error) {
  if (UnsupportedFunctionalityError.isInstance(error) &&
      error.functionality.includes('provider references')) {
    // rebuild prompt with url/data parts instead
  } else {
    throw error;
  }
}

Prevention

Never send file references built for OpenAI/other providers to Mistral.
Resolve references to bytes/URLs before provider dispatch.
Type prompts narrowly per provider to catch reference parts at compile time.

When it happens

Trigger: Including a message part of type 'file' whose data is { type: 'reference' } in a prompt sent to a Mistral model via generateText/streamText.

Common situations: Reusing prompts built for OpenAI's file-reference uploads with Mistral; sharing prompt-building helpers across providers that support file references.

Related errors

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