microsoft/semantic-kernel · error · ServiceInitializationError

Invalid settings: {exc}

Error message

Invalid settings: {exc}

What it means

Raised by AzureTextEmbedding.__init__ when AzureOpenAISettings construction throws a pydantic ValidationError. The settings model validates endpoint (HttpsUrl), base_url (Url), api_key (SecretStr), api_version (str). This class is decorated @experimental. Any field value that cannot be coerced to its declared type triggers the wrapped error.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/azure_text_embedding.py:77

        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.
        """
        try:
            azure_openai_settings = AzureOpenAISettings(
                env_file_path=env_file_path,
                api_key=api_key,
                embedding_deployment_name=deployment_name,
                endpoint=endpoint,
                base_url=base_url,
                api_version=api_version,
                token_endpoint=token_endpoint,
            )
        except ValidationError as exc:
            raise ServiceInitializationError(f"Invalid settings: {exc}") from exc
        if not azure_openai_settings.embedding_deployment_name:
            raise ServiceInitializationError("The Azure OpenAI embedding deployment name is required.")

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

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Inspect the chained ValidationError to identify the specific field and constraint that failed.
2. Ensure endpoint is a valid https:// URL ending in openai.azure.com.
3. Verify .env file syntax and that AZURE_OPENAI_ENDPOINT is correctly formatted.
4. Pass api_version as a string literal.

Example fix

# before
service = AzureTextEmbedding(
    deployment_name='text-embedding-3-large',
    endpoint='http://myresource.openai.azure.com',  # http rejected
    api_key='...',
)
# after
service = AzureTextEmbedding(
    deployment_name='text-embedding-3-large',
    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 = AzureTextEmbedding(
        deployment_name='text-embedding-3-large',
        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 AzureTextEmbedding with a non-HTTPS endpoint, a malformed base_url, or an AZURE_OPENAI_ENDPOINT env var with an invalid URL. Also triggered by passing api_version as a non-string.

Common situations: Passing endpoint='http://...' (HttpsUrl requires https scheme); bare hostname without scheme; .env file with corrupted values; environment variable set to an empty string in CI.

Related errors

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

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