{"record":{"id":"f2944c50961f29df","repo":"microsoft/semantic-kernel","slug":"the-api-key-is-required-when-use-vertexai-is-false-f2944c","errorCode":null,"errorMessage":"The API key is required when use_vertexai is False.","messagePattern":"The API key is required when use_vertexai is False\\.","errorType":"exception","errorClass":"ServiceInitializationError","httpStatus":null,"severity":"critical","filePath":"python/semantic_kernel/connectors/ai/google/google_ai/services/google_ai_text_embedding.py","lineNumber":87,"sourceCode":"                cloud_project_id=project_id,\n                cloud_region=region,\n                use_vertexai=use_vertexai,\n                env_file_path=env_file_path,\n                env_file_encoding=env_file_encoding,\n            )\n        except ValidationError as e:\n            raise ServiceInitializationError(f\"Failed to validate Google AI settings: {e}\") from e\n\n        if not google_ai_settings.embedding_model_id:\n            raise ServiceInitializationError(\"The Google AI embedding model ID is required.\")\n\n        if not client:\n            if google_ai_settings.use_vertexai and not google_ai_settings.cloud_project_id:\n                raise ServiceInitializationError(\"Project ID must be provided when use_vertexai is True.\")\n            if google_ai_settings.use_vertexai and not google_ai_settings.cloud_region:\n                raise ServiceInitializationError(\"Region must be provided when use_vertexai is True.\")\n            if not google_ai_settings.use_vertexai and not google_ai_settings.api_key:\n                raise ServiceInitializationError(\"The API key is required when use_vertexai is False.\")\n\n        super().__init__(\n            ai_model_id=google_ai_settings.embedding_model_id,\n            service_id=service_id or google_ai_settings.embedding_model_id,\n            service_settings=google_ai_settings,\n            client=client,\n        )\n\n    @override\n    async def generate_embeddings(\n        self,\n        texts: list[str],\n        settings: \"PromptExecutionSettings | None\" = None,\n        **kwargs: Any,\n    ) -> ndarray:\n        raw_embeddings = await self.generate_raw_embeddings(texts, settings, **kwargs)\n        return array(raw_embeddings)\n","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/ai/google/google_ai/services/google_ai_text_embedding.py#L69-L105","documentation":"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.","triggerScenarios":"Constructing GoogleAITextEmbedding() (use_vertexai defaults False) with no api_key argument and no GOOGLE_AI_API_KEY.","commonSituations":"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.","solutions":["Set GOOGLE_AI_API_KEY=<your-key> in your environment or .env file.","Pass api_key=<your-key> to the GoogleAITextEmbedding constructor.","If Vertex AI is intended, set use_vertexai=True and provide project_id and region."],"exampleFix":"# before\nembed = GoogleAITextEmbedding(embedding_model_id='text-embedding-004')\n\n# after\nembed = GoogleAITextEmbedding(embedding_model_id='text-embedding-004', api_key='AIza...')","handlingStrategy":"validation","validationCode":"import os\nuse_vertexai = os.environ.get('GOOGLE_AI_USE_VERTEXAI', 'false').lower() == 'true'\nif not use_vertexai and not os.environ.get('GOOGLE_AI_API_KEY'):\n    raise EnvironmentError('Set GOOGLE_AI_API_KEY for Gemini API (non-Vertex) embedding mode.')","typeGuard":null,"tryCatchPattern":"try:\n    service = GoogleAITextEmbedding()\nexcept ServiceInitializationError as e:\n    if 'API key is required' in str(e):\n        logging.error('Missing GOOGLE_AI_API_KEY for embedding service.')\n    raise","preventionTips":["Set GOOGLE_AI_API_KEY once in .env; both text and embedding services will pick it up.","Verify the env var name includes the GOOGLE_AI_ prefix.","Choose API-key vs Vertex-AI mode early and configure consistently across all services."],"tags":["google-ai","api-key","authentication","configuration","embeddings","constructor"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}