microsoft/semantic-kernel · critical · ServiceInitializationError

The API key is required when use_vertexai is False.

Error message

The API key is required when use_vertexai is False.

What it means

Raised in the GoogleAITextEmbedding constructor when use_vertexai is False (default) and no API key is available. The Gemini Developer API embedding endpoint authenticates with an API key. Without it the google.genai.Client cannot be built. The guard runs only when no custom client is supplied.

Source

Thrown at python/semantic_kernel/connectors/ai/google/google_ai/services/google_ai_text_embedding.py:87

                cloud_project_id=project_id,
                cloud_region=region,
                use_vertexai=use_vertexai,
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
            )
        except ValidationError as e:
            raise ServiceInitializationError(f"Failed to validate Google AI settings: {e}") from e

        if not google_ai_settings.embedding_model_id:
            raise ServiceInitializationError("The Google AI embedding model ID is required.")

        if not client:
            if google_ai_settings.use_vertexai and not google_ai_settings.cloud_project_id:
                raise ServiceInitializationError("Project ID must be provided when use_vertexai is True.")
            if google_ai_settings.use_vertexai and not google_ai_settings.cloud_region:
                raise ServiceInitializationError("Region must be provided when use_vertexai is True.")
            if not google_ai_settings.use_vertexai and not google_ai_settings.api_key:
                raise ServiceInitializationError("The API key is required when use_vertexai is False.")

        super().__init__(
            ai_model_id=google_ai_settings.embedding_model_id,
            service_id=service_id or google_ai_settings.embedding_model_id,
            service_settings=google_ai_settings,
            client=client,
        )

    @override
    async def generate_embeddings(
        self,
        texts: list[str],
        settings: "PromptExecutionSettings | None" = None,
        **kwargs: Any,
    ) -> ndarray:
        raw_embeddings = await self.generate_raw_embeddings(texts, settings, **kwargs)
        return array(raw_embeddings)

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set GOOGLE_AI_API_KEY=<your-key> in your environment or .env file.
2. Pass api_key=<your-key> to the GoogleAITextEmbedding constructor.
3. If Vertex AI is intended, set use_vertexai=True and provide project_id and region.

Example fix

# before
embed = GoogleAITextEmbedding(embedding_model_id='text-embedding-004')

# after
embed = GoogleAITextEmbedding(embedding_model_id='text-embedding-004', api_key='AIza...')

import os
use_vertexai = os.environ.get('GOOGLE_AI_USE_VERTEXAI', 'false').lower() == 'true'
if not use_vertexai and not os.environ.get('GOOGLE_AI_API_KEY'):
    raise EnvironmentError('Set GOOGLE_AI_API_KEY for Gemini API (non-Vertex) embedding mode.')

try:
    service = GoogleAITextEmbedding()
except ServiceInitializationError as e:
    if 'API key is required' in str(e):
        logging.error('Missing GOOGLE_AI_API_KEY for embedding service.')
    raise

When it happens

Trigger: Constructing GoogleAITextEmbedding() (use_vertexai defaults False) with no api_key argument and no GOOGLE_AI_API_KEY.

Common situations: Embedding service configured before setting the API key; .env file missing or not loaded; used GOOGLE_API_KEY instead of GOOGLE_AI_API_KEY; key is empty string.

Related errors

• The API key is required when use_vertexai is False.
• The API key is required when use_vertexai is False.
• The Google AI embedding model ID is required.
• Project ID must be provided when use_vertexai is True.
• Region must be provided when use_vertexai is True.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/f2944c50961f29df. Report an issue: GitHub.