microsoft/semantic-kernel · error · ServiceInitializationError

Region must be provided when use_vertexai is True.

Error message

Region must be provided when use_vertexai is True.

What it means

Raised in the GoogleAITextEmbedding constructor when use_vertexai is True but cloud_region is absent. The Vertex AI embedding endpoint requires a region/location to determine the endpoint URL. 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:85

                embedding_model_id=embedding_model_id,
                api_key=api_key,
                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)

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set GOOGLE_AI_CLOUD_REGION=<region> in your environment or .env file (e.g. GOOGLE_AI_CLOUD_REGION=us-central1).
2. Pass region=<region> to the GoogleAITextEmbedding constructor.
3. Supply a pre-configured google.genai Client if you manage the Vertex endpoint yourself.

Example fix

# before
embed = GoogleAITextEmbedding(use_vertexai=True, embedding_model_id='text-embedding-004', project_id='proj')

# after
embed = GoogleAITextEmbedding(
    use_vertexai=True, embedding_model_id='text-embedding-004',
    project_id='proj', region='us-central1',
)

import os
if os.environ.get('GOOGLE_AI_USE_VERTEXAI', '').lower() == 'true':
    if not os.environ.get('GOOGLE_AI_CLOUD_REGION'):
        raise EnvironmentError('Set GOOGLE_AI_CLOUD_REGION when using Vertex AI embeddings.')

try:
    service = GoogleAITextEmbedding(use_vertexai=True)
except ServiceInitializationError as e:
    if 'Region must be provided' in str(e):
        logging.error('Missing GOOGLE_AI_CLOUD_REGION for Vertex AI embedding service.')
    raise

When it happens

Trigger: Constructing GoogleAITextEmbedding(use_vertexai=True) without region and without GOOGLE_AI_CLOUD_REGION.

Common situations: Configured project_id but omitted region; env var GOOGLE_AI_CLOUD_REGION missing; used an alternative variable name.

Related errors

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

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