{"record":{"id":"aaa5a7b50512d834","repo":"microsoft/semantic-kernel","slug":"the-azure-openai-embedding-deployment-name-is-requ","errorCode":null,"errorMessage":"The Azure OpenAI embedding deployment name is required.","messagePattern":"The Azure OpenAI embedding deployment name is required\\.","errorType":"exception","errorClass":"ServiceInitializationError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/ai/open_ai/services/azure_text_embedding.py","lineNumber":79,"sourceCode":"        async_client (Optional[AsyncAzureOpenAI]): An existing client to use. (Optional)\n        env_file_path (str | None): Use the environment settings file as a fallback to\n            environment variables. (Optional)\n        credential (TokenCredential): The credential to use for authentication.\n        \"\"\"\n        try:\n            azure_openai_settings = AzureOpenAISettings(\n                env_file_path=env_file_path,\n                api_key=api_key,\n                embedding_deployment_name=deployment_name,\n                endpoint=endpoint,\n                base_url=base_url,\n                api_version=api_version,\n                token_endpoint=token_endpoint,\n            )\n        except ValidationError as exc:\n            raise ServiceInitializationError(f\"Invalid settings: {exc}\") from exc\n        if not azure_openai_settings.embedding_deployment_name:\n            raise ServiceInitializationError(\"The Azure OpenAI embedding deployment name is required.\")\n\n        super().__init__(\n            deployment_name=azure_openai_settings.embedding_deployment_name,\n            endpoint=azure_openai_settings.endpoint,\n            base_url=azure_openai_settings.base_url,\n            api_version=azure_openai_settings.api_version,\n            service_id=service_id,\n            api_key=azure_openai_settings.api_key.get_secret_value() if azure_openai_settings.api_key else None,\n            ad_token=ad_token,\n            ad_token_provider=ad_token_provider,\n            token_endpoint=azure_openai_settings.token_endpoint,\n            default_headers=default_headers,\n            ai_model_type=OpenAIModelTypes.EMBEDDING,\n            client=async_client,\n            credential=credential,\n        )\n\n    @classmethod","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/ai/open_ai/services/azure_text_embedding.py#L61-L97","documentation":"Raised by AzureTextEmbedding.__init__ after settings creation succeeds but embedding_deployment_name is empty or None. This field comes from the deployment_name constructor argument or the AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME environment variable. The embedding service requires a specific deployment name to target the correct model.","triggerScenarios":"Constructing AzureTextEmbedding without deployment_name= and without AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME set in the environment or .env file. Endpoint and auth resolved successfully, but the deployment identifier is missing.","commonSituations":"Using a generic AZURE_OPENAI_DEPLOYMENT_NAME instead of the embedding-specific variable; embedding model deployment created in Azure but the variable not added to config; .env file present but embedding line commented out; running in a fresh environment without the deployment env var.","solutions":["Pass deployment_name= explicitly: AzureTextEmbedding(deployment_name='text-embedding-3-large', ...).","Set AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME in your environment or .env file.","Verify the deployment exists in Azure Portal under Resource Management > Deployments and the name matches exactly."],"exampleFix":"# before\nservice = AzureTextEmbedding(\n    endpoint='https://myresource.openai.azure.com',\n    api_key='...',\n)\n# after\nservice = AzureTextEmbedding(\n    deployment_name='text-embedding-3-large',\n    endpoint='https://myresource.openai.azure.com',\n    api_key='...',\n)","handlingStrategy":"validation","validationCode":"import os\n\ndeployment_name = os.environ.get('AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME')\nif not deployment_name:\n    raise ValueError(\n        'AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME is not set. '\n        'Set it in your environment or .env file, or pass deployment_name= to the constructor.'\n    )","typeGuard":null,"tryCatchPattern":"from semantic_kernel.exceptions.service_exceptions import ServiceInitializationError\n\ntry:\n    service = AzureTextEmbedding(\n        deployment_name=os.environ.get('AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME'),\n        endpoint='https://myresource.openai.azure.com',\n        api_key='...',\n    )\nexcept ServiceInitializationError as e:\n    if 'embedding deployment name is required' in str(e):\n        print('Set AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME or pass deployment_name=')\n    raise","preventionTips":["Set AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME in your environment or .env file.","Always pass deployment_name= explicitly in the constructor.","Verify the deployment name exists in Azure Portal > Resource Management > Deployments.","Use the embedding-specific env var, not a chat or generic one."],"tags":["azure-openai","embedding","deployment-name","env-vars","experimental"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}