microsoft/semantic-kernel · error · ServiceInitializationError

chat_deployment_name is required.

Error message

chat_deployment_name is required.

What it means

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.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/azure_chat_completion.py:102

                prompts could use `developer` or `system`. (Optional)
            credential (TokenCredential): The credential to use for authentication.
        """
        try:
            azure_openai_settings = AzureOpenAISettings(
                api_key=api_key,
                base_url=base_url,
                endpoint=endpoint,
                chat_deployment_name=deployment_name,
                api_version=api_version,
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
                token_endpoint=token_endpoint,
            )
        except ValidationError as exc:
            raise ServiceInitializationError(f"Failed to validate settings: {exc}") from exc

        if not azure_openai_settings.chat_deployment_name:
            raise ServiceInitializationError("chat_deployment_name is required.")

        super().__init__(
            deployment_name=azure_openai_settings.chat_deployment_name,
            endpoint=azure_openai_settings.endpoint,
            base_url=azure_openai_settings.base_url,
            api_version=azure_openai_settings.api_version,
            service_id=service_id,
            api_key=azure_openai_settings.api_key.get_secret_value() if azure_openai_settings.api_key else None,
            ad_token=ad_token,
            ad_token_provider=ad_token_provider,
            token_endpoint=azure_openai_settings.token_endpoint,
            default_headers=default_headers,
            ai_model_type=OpenAIModelTypes.CHAT,
            client=async_client,
            instruction_role=instruction_role,
            credential=credential,
        )

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass deployment_name explicitly: AzureChatCompletionService(deployment_name='gpt-4o', ...).
2. Set AZURE_OPENAI_CHAT_DEPLOYMENT_NAME in your .env file or environment.
3. Verify the deployment name matches an actual model deployment in your Azure OpenAI resource.

Example fix

// before
service = AzureChatCompletionService(endpoint='...', api_key='...')  # no deployment_name
// after
service = AzureChatCompletionService(
    deployment_name='gpt-4o',
    endpoint='https://my-resource.openai.azure.com/',
    api_key='...'
)

def validate_chat_deployment_name(deployment_name: str | None) -> None:
    if not deployment_name:
        import os
        if not os.environ.get('AZURE_OPENAI_CHAT_DEPLOYMENT_NAME'):
            raise ValueError(
                'chat_deployment_name is required. '
                'Pass deployment_name or set AZURE_OPENAI_CHAT_DEPLOYMENT_NAME.'
            )

def has_chat_deployment_name(deployment_name: str | None) -> bool:
    import os
    return bool(deployment_name or os.environ.get('AZURE_OPENAI_CHAT_DEPLOYMENT_NAME'))

from semantic_kernel.exceptions import ServiceInitializationError

try:
    service = AzureChatCompletionService(endpoint=ep, api_key=key)
except ServiceInitializationError as e:
    if 'chat_deployment_name is required' in str(e):
        service = AzureChatCompletionService(deployment_name='gpt-4o', endpoint=ep, api_key=key)

When it happens

Trigger: Constructing AzureChatCompletionService without deployment_name and without AZURE_OPENAI_CHAT_DEPLOYMENT_NAME in the environment; passing deployment_name=None or deployment_name=''.

Common situations: 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.

Related errors

• Please provide an Azure OpenAI Responses deployment name
• The Azure OpenAI audio to text deployment name is required.
• Failed to validate settings: {exc}
• Expected AzureOpenAISettings, got {type(settings).__name__}
• Failed to create Azure OpenAI settings: {exc}

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