microsoft/semantic-kernel · error · ServiceInitializationError

Failed to validate settings: {exc}

Error message

Failed to validate settings: {exc}

What it means

When constructing AzureChatCompletionService, the AzureOpenAISettings pydantic model is validated from constructor arguments and environment variables. If pydantic raises a ValidationError, it's caught and re-raised as ServiceInitializationError with the message 'Failed to validate settings' plus the full validation error detail. This is a construction-time configuration error.

Source

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

            env_file_path (str | None): Use the environment settings file as a fallback to using env vars.
            env_file_encoding (str | None): The encoding of the environment settings file, defaults to 'utf-8'.
            instruction_role (str | None): The role to use for 'instruction' messages, for example, summarization
                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,

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Read the ValidationError detail in the exception message — pydantic specifies each failing field and the reason.
2. Fix the flagged fields: ensure endpoint is a valid https URL, api_version is YYYY-MM-DD-preview format.
3. Verify your .env file is loaded (call load_dotenv() or pass env_file_path).
4. Pass settings explicitly in the constructor to bypass env var issues during debugging.

Example fix

// before
service = AzureChatCompletionService(deployment_name='gpt-4', endpoint='localhost:8080')
// after
service = AzureChatCompletionService(
    deployment_name='gpt-4',
    endpoint='https://my-resource.openai.azure.com/',
    api_key='...',
    api_version='2024-02-15-preview'
)

def validate_azure_chat_settings_kwargs(endpoint: str, api_version: str) -> None:
    if endpoint and not endpoint.startswith('https://'):
        raise ValueError(f'endpoint must be an https URL, got: {endpoint}')
    if api_version:
        import re
        if not re.match(r'^\d{4}-\d{2}-\d{2}', api_version):
            raise ValueError(f'api_version should be YYYY-MM-DD format, got: {api_version}')

def are_azure_chat_args_valid(endpoint: str, api_version: str) -> bool:
    import re
    if endpoint and not endpoint.startswith('https://'):
        return False
    if api_version and not re.match(r'^\d{4}-\d{2}-\d{2}', api_version):
        return False
    return True

from semantic_kernel.exceptions import ServiceInitializationError

try:
    service = AzureChatCompletionService(endpoint=ep, api_key=key, deployment_name=dep)
except ServiceInitializationError as e:
    print(f'Settings validation failed: {e}')
    # read the pydantic error detail to fix the specific field

When it happens

Trigger: Passing invalid constructor values to AzureChatCompletionService (malformed endpoint URL, wrong api_version format, invalid base_url) or having malformed AZURE_OPENAI_* environment variables that fail pydantic validation.

Common situations: Typo in AZURE_OPENAI_ENDPOINT (missing https://); AZURE_OPENAI_API_VERSION in wrong format; .env file not loaded (python-dotenv not called); invalid characters in env values; SDK upgrade adding new required or constrained fields.

Related errors

• Invalid settings: {exc}
• Failed to create Azure OpenAI settings: {exc}
• chat_deployment_name is required.
• Expected AzureOpenAISettings, got {type(settings).__name__}
• Please provide either an api_key, ad_token, ad_token_provide

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