microsoft/semantic-kernel · error · ServiceInitializationError

Invalid settings: {exc}

Error message

Invalid settings: {exc}

What it means

When constructing an AzureOpenAIAudioToTextService, the AzureOpenAISettings pydantic model is validated from constructor arguments and environment. If pydantic raises a ValidationError (e.g. wrong type, invalid URL, missing required env), it's caught and re-raised as ServiceInitializationError with the validation details. This is a configuration/initialization-time error, not a runtime API error.

Source

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

            async_client: An existing client to use. (Optional)
            env_file_path: Use the environment settings file as a fallback to
                environment variables. (Optional)
            env_file_encoding: The encoding of the environment settings file. (Optional)
            credential: The credential to use for authentication. (Optional)
        """
        try:
            azure_openai_settings = AzureOpenAISettings(
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
                api_key=api_key,
                audio_to_text_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.audio_to_text_deployment_name:
            raise ServiceInitializationError("The Azure OpenAI audio to text deployment name is required.")

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

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Read the full validation error in the exception message — pydantic lists each failing field and why.
2. Fix the specific field(s) flagged by the ValidationError (type, format, missing value).
3. Validate environment variables: ensure AZURE_OPENAI_ENDPOINT is a full https URL and AZURE_OPENAI_API_VERSION follows the YYYY-MM-DD format.
4. Pass values explicitly in the constructor to isolate which source is malformed.

Example fix

// before
service = AzureOpenAIAudioToTextService(endpoint='my-resource', api_version='v1')
// after
service = AzureOpenAIAudioToTextService(
    endpoint='https://my-resource.openai.azure.com/',
    api_version='2024-02-15-preview',
    api_key='...',
    deployment_name='whisper'
)

def validate_azure_settings_kwargs(endpoint: str, api_version: str, api_key: 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}')
    if not api_key:
        raise ValueError('api_key is required')

def are_azure_settings_args_valid(endpoint, api_version, api_key) -> 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 bool(api_key)

from semantic_kernel.exceptions import ServiceInitializationError

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

When it happens

Trigger: Passing invalid values to AzureOpenAIAudioToTextService constructor (e.g. endpoint as a non-URL string, api_version in wrong format) or having malformed AZURE_OPENAI_* environment variables. The ValidationError is caught at construction time.

Common situations: Environment variables with typos or wrong formats (e.g. AZURE_OPENAI_ENDPOINT without https://); passing endpoint='my-endpoint' instead of endpoint='https://my-resource.openai.azure.com/'; .env file with encoding issues; missing pydantic-required fields after an SDK upgrade.

Related errors

• Failed to validate settings: {exc}
• Failed to create Azure OpenAI settings: {exc}
• The Azure OpenAI audio to text 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/8aff0e4247d8ba68. Report an issue: GitHub.