{"record":{"id":"016d2cee61191080","repo":"microsoft/semantic-kernel","slug":"chat-deployment-name-is-required","errorCode":null,"errorMessage":"chat_deployment_name is required.","messagePattern":"chat_deployment_name is required\\.","errorType":"exception","errorClass":"ServiceInitializationError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/ai/open_ai/services/azure_chat_completion.py","lineNumber":102,"sourceCode":"                prompts could use `developer` or `system`. (Optional)\n            credential (TokenCredential): The credential to use for authentication.\n        \"\"\"\n        try:\n            azure_openai_settings = AzureOpenAISettings(\n                api_key=api_key,\n                base_url=base_url,\n                endpoint=endpoint,\n                chat_deployment_name=deployment_name,\n                api_version=api_version,\n                env_file_path=env_file_path,\n                env_file_encoding=env_file_encoding,\n                token_endpoint=token_endpoint,\n            )\n        except ValidationError as exc:\n            raise ServiceInitializationError(f\"Failed to validate settings: {exc}\") from exc\n\n        if not azure_openai_settings.chat_deployment_name:\n            raise ServiceInitializationError(\"chat_deployment_name is required.\")\n\n        super().__init__(\n            deployment_name=azure_openai_settings.chat_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.CHAT,\n            client=async_client,\n            instruction_role=instruction_role,\n            credential=credential,\n        )\n","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/ai/open_ai/services/azure_chat_completion.py#L84-L120","documentation":"After AzureOpenAISettings validates successfully for AzureChatCompletionService, the constructor checks that chat_deployment_name is set (truthy). If it's empty/None — either because deployment_name wasn't passed to the constructor and no AZURE_OPENAI_CHAT_DEPLOYMENT_NAME env var is set — it raises ServiceInitializationError.","triggerScenarios":"Constructing AzureChatCompletionService without deployment_name and without AZURE_OPENAI_CHAT_DEPLOYMENT_NAME in the environment; passing deployment_name=None or deployment_name=''.","commonSituations":"New project where the env var hasn't been configured; typo in the env var name (e.g. AZURE_OPENAI_DEPLOYMENT_NAME instead of AZURE_OPENAI_CHAT_DEPLOYMENT_NAME); .env file not loaded; copy-pasting code that relied on a default that doesn't exist.","solutions":["Pass deployment_name explicitly: AzureChatCompletionService(deployment_name='gpt-4o', ...).","Set AZURE_OPENAI_CHAT_DEPLOYMENT_NAME in your .env file or environment.","Verify the deployment name matches an actual model deployment in your Azure OpenAI resource."],"exampleFix":"// before\nservice = AzureChatCompletionService(endpoint='...', api_key='...')  # no deployment_name\n// after\nservice = AzureChatCompletionService(\n    deployment_name='gpt-4o',\n    endpoint='https://my-resource.openai.azure.com/',\n    api_key='...'\n)","handlingStrategy":"validation","validationCode":"def validate_chat_deployment_name(deployment_name: str | None) -> None:\n    if not deployment_name:\n        import os\n        if not os.environ.get('AZURE_OPENAI_CHAT_DEPLOYMENT_NAME'):\n            raise ValueError(\n                'chat_deployment_name is required. '\n                'Pass deployment_name or set AZURE_OPENAI_CHAT_DEPLOYMENT_NAME.'\n            )","typeGuard":"def has_chat_deployment_name(deployment_name: str | None) -> bool:\n    import os\n    return bool(deployment_name or os.environ.get('AZURE_OPENAI_CHAT_DEPLOYMENT_NAME'))","tryCatchPattern":"from semantic_kernel.exceptions import ServiceInitializationError\n\ntry:\n    service = AzureChatCompletionService(endpoint=ep, api_key=key)\nexcept ServiceInitializationError as e:\n    if 'chat_deployment_name is required' in str(e):\n        service = AzureChatCompletionService(deployment_name='gpt-4o', endpoint=ep, api_key=key)","preventionTips":["Always pass deployment_name explicitly or set AZURE_OPENAI_CHAT_DEPLOYMENT_NAME.","Verify the deployment exists in your Azure OpenAI resource.","Validate deployment names at application startup."],"tags":["azure-openai","chat-completion","deployment-name","initialization","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}