vercel/ai · error · UnsupportedFunctionalityError

'file parts with provider references' functionality is not s

Error message

'file parts with provider references' functionality is not supported.

What it means

Provider-reference file parts (files referenced by a provider-specific ID/URI rather than inline data) are supported on Google's first-party Gemini API but not on Vertex AI endpoints. When converting a user file part of type 'reference' while running against a Vertex-like endpoint (isVertexLike), the converter throws UnsupportedFunctionalityError.

Source

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

            case 'text': {
              parts.push({ text: part.text });
              break;
            }

            case 'file': {
              switch (part.data.type) {
                case 'url': {
                  parts.push({
                    fileData: {
                      mimeType: resolveFullMediaType({ part }),
                      fileUri: part.data.url.toString(),
                    },
                  });
                  break;
                }
                case 'reference': {
                  if (isVertexLike) {
                    throw new UnsupportedFunctionalityError({
                      functionality: 'file parts with provider references',
                    });
                  }

                  parts.push({
                    fileData: {
                      mimeType: resolveFullMediaType({ part }),
                      fileUri: resolveProviderReference({
                        reference: part.data.reference,
                        provider: 'google',
                      }),
                    },
                  });
                  break;
                }
                case 'text': {
                  parts.push({
                    inlineData: {

View on GitHub (pinned to 69428b1f8b)

Solutions

Send the file as inline base64 data (`type: 'data'`) instead of a provider reference when using Vertex.
Upload the file to Vertex/Cloud Storage and pass a GCS URI via the Vertex-specific file data format.
Switch to the first-party Google provider (Google AI Studio endpoint) which supports file references.

Example fix

// before
{ role: 'user', content: [{ type: 'file', data: { type: 'reference', fileId: 'files/abc' } }] }
// after
{ role: 'user', content: [{ type: 'file', data: { type: 'data', mediaType: 'application/pdf', data: base64Pdf } }] }

Defensive patterns

Strategy: validation

Validate before calling

function filePartsAreVertexSafe(messages) {
  return messages.flatMap(m => Array.isArray(m.content) ? m.content : []).every(p =>
    p.type !== 'file' || p.data?.type !== 'reference');
}
// run before sending to a Vertex model

Type guard

function isInlineDataFilePart(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')) {
    // convert references to inline base64 or GCS URIs and retry
  } throw e;
}

Prevention

Know your endpoint: Vertex does not accept Gemini Files-API references.
Resolve file references to bytes or GCS URIs before building messages.
Keep separate message-shaping code paths for Google AI vs Vertex.

When it happens

Trigger: Passing a user message file part with `data: { type: 'reference', ... }` (e.g. a Vertex/Google file reference) to a model created via the google-vertex provider, or to google provider configured in Vertex-like mode.

Common situations: Reusing Gemini-API message code that references uploaded Files against Vertex; caching file references from a previous Gemini call and replaying them through Vertex; mixing provider models in one agent with shared message history.

Related errors

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