vercel/ai · error · UnsupportedFunctionalityError

'file parts with provider references' functionality not supp

Error message

'file parts with provider references' functionality not supported.

What it means

Like error 335 but for assistant messages: file parts that use provider references (provider-specific file IDs) inside an assistant message are rejected when targeting Vertex-like Google endpoints (isVertexLike), because Vertex does not accept Gemini-API file references. The converter throws UnsupportedFunctionalityError.

Source

Thrown at packages/google/src/convert-to-google-messages.ts:412

                        thought: true,
                        thoughtSignature,
                      };
                    }
                  }
                  break;
                }

                case 'file': {
                  switch (part.data.type) {
                    case 'url': {
                      throw new UnsupportedFunctionalityError({
                        functionality:
                          'File data URLs in assistant messages are not supported',
                      });
                    }
                    case 'reference': {
                      if (isVertexLike) {
                        throw new UnsupportedFunctionalityError({
                          functionality: 'file parts with provider references',
                        });
                      }

                      return {
                        fileData: {
                          mimeType: part.mediaType,
                          fileUri: resolveProviderReference({
                            reference: part.data.reference,
                            provider: 'google',
                          }),
                        },
                        ...(providerOpts?.thought === true
                          ? { thought: true }
                          : {}),
                        thoughtSignature,
                      };
                    }

View on GitHub (pinned to 69428b1f8b)

Solutions

Send the file as inline base64 data instead of a provider reference.
Upload to Cloud Storage and reference via the Vertex-supported GCS URI format.
Strip provider-reference file parts from history when routing to Vertex models.

Example fix

// before
{ role: 'assistant', content: [{ type: 'file', data: { type: 'reference', fileId: 'files/abc' } }] }
// after
{ role: 'assistant', content: [{ type: 'file', data: { type: 'data', mediaType: 'image/png', data: base64Png } }] }

Defensive patterns

Strategy: validation

Validate before calling

function assistantFileRefsVertexSafe(messages) {
  return messages.flatMap(m => m.role === 'assistant' && Array.isArray(m.content) ? m.content : [])
    .every(p => p.type !== 'file' || p.data?.type !== 'reference');
}
// check when target is a Vertex model

Type guard

function isAssistantInlineDataFile(part) {
  return part?.type === 'file' && part?.data?.type === 'data' && typeof part.data.data === 'string';
}

Try / catch

try {
  await streamText({ model: vertexModel, messages });
} catch (e) {
  if (e?.message?.includes('file parts with provider references')) {
    // inline base64 or GCS URI, then retry
  } throw e;
}

Prevention

Never persist provider file IDs in cross-provider conversation logs.
Inline file bytes for assistant messages when routing to Vertex.
Feature-detect target endpoint (Vertex vs Gemini) before composing file parts.

When it happens

Trigger: An assistant message containing a `file` part with `data: { type: 'reference', ... }` sent to a Google Vertex model via convertToGoogleMessages.

Common situations: Replaying Gemini-API assistant outputs (which contain Files API references) against Vertex; shared message stores across Google and Vertex deployments.

Related errors

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