microsoft/semantic-kernel · error · ServiceInitializationError

Invalid settings

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.

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='...',
)
Defensive patterns

Strategy: try-catch

Validate before calling

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'))

Try / catch

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

Prevention

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

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

Appendix: 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)