microsoft/semantic-kernel · error · ServiceInitializationError

The Azure Text deployment name is required.

Error message

The Azure Text deployment name is required.

What it means

Raised by AzureTextCompletion.__init__ after settings creation succeeds but the text_deployment_name field is empty or None. This field is sourced from the deployment_name constructor argument or the AZURE_OPENAI_TEXT_DEPLOYMENT_NAME environment variable. Without it, the service cannot target a specific model deployment. Note: AzureTextCompletion is deprecated — all Azure OpenAI text completion models have been retired.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/azure_text_completion.py:89

            async_client (Optional[AsyncAzureOpenAI]): An existing client to use. (Optional)
            env_file_path (str | None): Use the environment settings file as a fallback to
                environment variables. (Optional)
            credential (TokenCredential): The credential to use for authentication. (Optional)
        """
        try:
            azure_openai_settings = AzureOpenAISettings(
                env_file_path=env_file_path,
                text_deployment_name=deployment_name,
                endpoint=endpoint,
                base_url=base_url,
                api_key=api_key,
                api_version=api_version,
                token_endpoint=token_endpoint,
            )
        except ValidationError as ex:
            raise ServiceInitializationError(f"Invalid settings: {ex}") from ex
        if not azure_openai_settings.text_deployment_name:
            raise ServiceInitializationError("The Azure Text deployment name is required.")

        super().__init__(
            deployment_name=azure_openai_settings.text_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.TEXT,
            client=async_client,
            credential=credential,
        )

    @classmethod

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Migrate to AzureChatCompletion and use AZURE_OPENAI_CHAT_DEPLOYMENT_NAME — text completion models are retired on Azure.
2. If required, pass deployment_name= explicitly in the constructor.
3. Set AZURE_OPENAI_TEXT_DEPLOYMENT_NAME in your environment or .env file.

Example fix

# before
service = AzureTextCompletion(
    endpoint='https://myresource.openai.azure.com',
    api_key='...',
)
# after (migrate to chat completion)
service = AzureChatCompletion(
    deployment_name='gpt-4o',
    endpoint='https://myresource.openai.azure.com',
    api_key='...',
)

import os

deployment_name = os.environ.get('AZURE_OPENAI_TEXT_DEPLOYMENT_NAME')
if not deployment_name:
    raise ValueError(
        'AZURE_OPENAI_TEXT_DEPLOYMENT_NAME is not set. Note: Azure text completion models are retired — '
        'consider migrating to AzureChatCompletion with AZURE_OPENAI_CHAT_DEPLOYMENT_NAME.'
    )

from semantic_kernel.exceptions.service_exceptions import ServiceInitializationError

try:
    service = AzureTextCompletion(
        deployment_name=os.environ.get('AZURE_OPENAI_TEXT_DEPLOYMENT_NAME'),
        endpoint='https://myresource.openai.azure.com',
        api_key='...',
    )
except ServiceInitializationError as e:
    if 'deployment name is required' in str(e):
        print('Set AZURE_OPENAI_TEXT_DEPLOYMENT_NAME or migrate to AzureChatCompletion')
    raise

When it happens

Trigger: Constructing AzureTextCompletion without deployment_name= and without AZURE_OPENAI_TEXT_DEPLOYMENT_NAME in the environment or .env file. Settings otherwise validated (endpoint, auth resolved) but the deployment name is absent.

Common situations: Using AZURE_OPENAI_CHAT_DEPLOYMENT_NAME (chat-specific) instead of the text-specific variable; deployment was never configured in Azure Portal; .env file missing the text deployment line. The underlying issue may be moot since text completion models are retired.

Related errors

• The OpenAI realtime model ID is required.
• Invalid settings: {ex}
• The Azure OpenAI embedding deployment name is required.
• The Azure OpenAI text to audio deployment name is required.
• The Azure OpenAI text to image deployment name is required.

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