microsoft/semantic-kernel · error · ServiceInitializationError

Invalid settings: {ex}

Error message

Invalid settings: {ex}

What it means

Raised by AzureTextCompletion.__init__ when AzureOpenAISettings construction throws a pydantic ValidationError. Note: AzureTextCompletion itself is decorated @deprecated (all Azure OpenAI text completion models have retired). The settings model validates endpoint as HttpsUrl, base_url as Url, api_key as SecretStr, and api_version as str. Any field failing coercion produces the wrapped error.

Source

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

            default_headers: The default headers mapping of string keys to
                string values for HTTP requests. (Optional)
            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,
        )

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Migrate from AzureTextCompletion to AzureChatCompletion — Azure OpenAI text completion models are retired and this class is deprecated for removal after 2026-01-01.
2. If you must use it, inspect the chained ValidationError for the specific failing field.
3. Ensure endpoint is a full https:// URL (e.g. 'https://myresource.openai.azure.com').
4. Pass api_version as a string.

Example fix

# before (deprecated class with invalid endpoint)
service = AzureTextCompletion(
    deployment_name='text-davinci-003',
    endpoint='myresource.openai.azure.com',
    api_key='...',
)
# after (migrate to chat completion with valid endpoint)
service = AzureChatCompletion(
    deployment_name='gpt-4o',
    endpoint='https://myresource.openai.azure.com',
    api_key='...',
)

from urllib.parse import urlparse

def validate_azure_endpoint(endpoint: str | None) -> str:
    if endpoint is None:
        raise ValueError('endpoint is required')
    parsed = urlparse(endpoint)
    if parsed.scheme != 'https':
        raise ValueError(f'endpoint must use https:// scheme, got {parsed.scheme}://')
    return endpoint

validate_azure_endpoint(os.environ.get('AZURE_OPENAI_ENDPOINT'))

from semantic_kernel.exceptions.service_exceptions import ServiceInitializationError

try:
    service = AzureTextCompletion(
        deployment_name='text-davinci-003',
        endpoint='https://myresource.openai.azure.com',
        api_key='...',
    )
except ServiceInitializationError as e:
    cause = e.__cause__
    if cause:
        print(f'Settings validation failed: {cause}')
    raise

When it happens

Trigger: Constructing the deprecated AzureTextCompletion with an endpoint that is not a valid HTTPS URL, a malformed base_url value, or an AZURE_OPENAI_ENDPOINT env var containing an invalid URL. Also triggered by passing api_version as a non-string type.

Common situations: Still using AzureTextCompletion after Azure retired all text completion models (should migrate to AzureChatCompletion); passing 'http://...' for endpoint; .env file with a broken endpoint value; version upgrade where field types became stricter (str to HttpsUrl).

Related errors

• Failed to create OpenAI settings.
• The Azure Text deployment name is required.
• Invalid settings: {exc}
• Invalid settings: {exc}
• Invalid settings: {exc}

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