vercel/ai · error · Error

Google Vertex tuned models do not support Express Mode API k

Error message

Google Vertex tuned models do not support Express Mode API keys. Use standard Google Cloud credentials instead.

What it means

createChatModel in the Vertex provider base throws this Error when a model id that resolves to a tuned-model endpoint is combined with Express Mode API-key authentication. Tuned Vertex endpoints require standard Google Cloud auth (service account / ADC), so the provider rejects the combination at model creation time.

Source

Thrown at packages/google-vertex/src/google-vertex-provider-base.ts:281

        `ai-sdk/google-vertex/${VERSION}`,
      );
    };

    return {
      provider: `google.vertex.${name}`,
      headers: getHeaders,
      fetch: apiKey
        ? createExpressModeFetch(apiKey, options.fetch)
        : options.fetch,
      baseURL: loadBaseURL({ endpoint }),
    };
  };

  const createChatModel = (modelId: GoogleVertexModelId) => {
    const endpoint = isEndpointModelId(modelId);

    if (endpoint && apiKey) {
      throw new Error(
        'Google Vertex tuned models do not support Express Mode API keys. Use standard Google Cloud credentials instead.',
      );
    }

    return new GoogleLanguageModel(modelId, {
      ...createConfig('chat', { endpoint }),
      generateId: options.generateId ?? generateId,
      supportedUrls: () => ({
        '*': [
          // HTTP URLs:
          /^https?:\/\/.*$/,
          // Google Cloud Storage URLs:
          /^gs:\/\/.*$/,
        ],
      }),
    });
  };

View on GitHub (pinned to 69428b1f8b)

Solutions

Remove the apiKey / GOOGLE_VERTEX_API_KEY and authenticate with service-account credentials (GOOGLE_SERVICE_ACCOUNT_KEY / GOOGLE_APPLICATION_CREDENTIALS or workload identity).
Use a base model id instead of a tuned endpoint if Express Mode must be kept.
Create a second provider instance without apiKey specifically for tuned endpoint models.

Example fix

// before
const vertex = createGoogleVertex({ apiKey: process.env.GOOGLE_VERTEX_API_KEY });
const model = vertex('projects/p/locations/us-central1/endpoints/123');
// after
const vertex = createGoogleVertex({ project: 'p', location: 'us-central1' }); // ADC/service account
const model = vertex('projects/p/locations/us-central1/endpoints/123');

Defensive patterns

Strategy: validation

Validate before calling

const usingApiKey = Boolean(process.env.GOOGLE_VERTEX_API_KEY || apiKeyOption);
const isEndpointModel = modelId.includes('/endpoints/');
if (usingApiKey && isEndpointModel) {
  throw new Error('Tuned Vertex endpoints require service-account auth, not an Express Mode API key.');
}

Try / catch

try {
  return vertex(modelId);
} catch (e) {
  if (e instanceof Error && e.message.includes('Express Mode API keys')) {
    // recreate provider with ADC/service-account credentials
  } else throw e;
}

Prevention

Don't set GOOGLE_VERTEX_API_KEY in environments that also use tuned endpoints.
Use workload identity or GOOGLE_APPLICATION_CREDENTIALS as the default Vertex auth.
Document that Express Mode API keys only support base chat models.

When it happens

Trigger: Constructing vertex('projects/.../locations/.../endpoints/...') or an endpoint-style tuned model id while the provider was configured with `apiKey` (Express Mode), e.g. createGoogleVertex({ apiKey: ... }) or GOOGLE_VERTEX_API_KEY set — `isEndpointModelId(modelId)` is true and `apiKey` is set.

Common situations: Using an Express Mode API key for quick local prototyping, then switching to a tuned/deployed model endpoint; CI environments where GOOGLE_VERTEX_API_KEY is exported alongside endpoint model ids; misunderstanding that Express Mode covers all Vertex features.

Related errors

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