CherryHQ/cherry-studio · error · Error

VertexAI requires iam-gcp auth configuration.

Error message

VertexAI requires iam-gcp auth configuration.

What it means

Provider-config build error for `google-vertex` / `google-vertex-maas`. `buildVertexConfig` calls `providerService.getAuthConfig(providerId)` and requires the result's `type` to be exactly `'iam-gcp'`. Anything else — no auth config at all, an `api-key` config, or an incomplete iam-gcp config — throws a plain `Error` (not an McpError). This blocks provider config construction before any request is sent, because VertexAI has no API-key path in this codebase (unlike Bedrock, which has an api-key fallback at line 578).

Source

Thrown at src/main/ai/provider/config.ts:591

      credentialReceipt: { attribution: 'auth', method: 'iam-aws' }
    }
  }

  // API-key fallback. Region undefined so the SDK picks its own default, not a hardcode.
  const selected = selectApiKey(ctx)
  return {
    config: { ...base, providerSettings: { ...selected.baseConfig, baseURL } },
    credentialReceipt: selected.apiKeySelection
  }
}

function buildVertexConfig(
  ctx: BuilderContext
): ProviderConfig<'google-vertex'> | ProviderConfig<'google-vertex-maas'> {
  const authConfig = providerService.getAuthConfig(ctx.actualProvider.id)

  if (authConfig?.type !== 'iam-gcp') {
    throw new Error('VertexAI requires iam-gcp auth configuration.')
  }

  const { project, location, credentials } = authConfig
  const googleCredentials = credentials as Record<string, string> | undefined

  const { privateKey, clientEmail } = normalizeVertexCredentials(googleCredentials)
  const creds = googleCredentials
    ? { ...googleCredentials, clientEmail, privateKey: formatPrivateKey(privateKey ?? '') }
    : undefined

  const modelId = ctx.model.apiModelId ?? ctx.model.id
  const isAnthropic = ctx.aiSdkProviderId === 'google-vertex-anthropic' || modelId.startsWith('claude')

  // MaaS open/partner models (Llama, DeepSeek, Qwen, GLM, Kimi, gpt-oss) are served over
  // Vertex's OpenAI-compatible Chat Completions endpoint, not the Gemini generateContent
  // SDK that `google-vertex` uses. They carry a `{publisher}/{model}` id — the model listing
  // bakes the publisher prefix in (§listModels/vertex), and that same id is the `model` the
  // OpenAI-compatible endpoint expects. Route them to the dedicated MaaS adapter, which mints

View on GitHub (pinned to 726446b54c)

Solutions

1. Configure the VertexAI provider with `iam-gcp` auth: a GCP project, location, and service-account credentials (client_email + private_key).
2. If you only have a Gemini API key, use the `google` provider instead of `google-vertex`.
3. Verify `providerService.getAuthConfig(providerId)` returns `{ type: 'iam-gcp', project, location, credentials }` before building the config.
4. Re-paste the service-account JSON and confirm the private key parses (it is normalized via `normalizeVertexCredentials` + `formatPrivateKey`).

// Before building config, assert the auth shape VertexAI requires.
function assertVertexAuth(authConfig: unknown): asserts authConfig is {
  type: 'iam-gcp'; project: string; location: string; credentials?: Record<string, string>
} {
  if (!authConfig || (authConfig as any).type !== 'iam-gcp') {
    throw new Error('VertexAI requires iam-gcp auth: set type=iam-gcp, project, location, and service-account credentials.')
  }
  if (typeof (authConfig as any).project !== 'string' || typeof (authConfig as any).location !== 'string') {
    throw new Error('iam-gcp auth requires both project and location.')
  }
}

const isIamGcpAuth = (v: unknown): v is { type: 'iam-gcp'; project: string; location: string; credentials?: Record<string, string> } =>
  typeof v === 'object' && v !== null &&
  (v as any).type === 'iam-gcp' &&
  typeof (v as any).project === 'string' &&
  typeof (v as any).location === 'string'

const authConfig = providerService.getAuthConfig(providerId)
try {
  assertVertexAuth(authConfig)
} catch (e) {
  // e.message === 'VertexAI requires iam-gcp auth configuration.'
  // guide the user to either configure iam-gcp or switch to the 'google' (API-key) provider
  throw e
}

When it happens

Trigger: Selecting a `google-vertex` provider whose auth settings are missing, set to `api-key`, or set to an auth type other than `iam-gcp`; a partially configured iam-gcp record (e.g. only project, no service-account credentials).

Common situations: User picked VertexAI but only filled in an API key (which works for Gemini direct but not Vertex); service-account JSON not pasted or malformed; provider record created without auth; auth config cleared during a settings migration.

Related errors

• Provider extension "${id}" not found. Did you forget to regi
• Rerank response results must reference a valid document inde
• OpenAI-compatible reranking model requires baseURL
• Private key must be a non-empty string
• Invalid PEM format: missing BEGIN/END markers or key content

AI-assisted analysis of CherryHQ/cherry-studio@726446b54c (2026-08-12). Data as JSON: /api/errors/db760d5b76ba5802. Report an issue: GitHub.