{"record":{"id":"8aff0e4247d8ba68","repo":"microsoft/semantic-kernel","slug":"invalid-settings-exc","errorCode":null,"errorMessage":"Invalid settings: {exc}","messagePattern":"Invalid settings: (.+?)","errorType":"exception","errorClass":"ServiceInitializationError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/ai/open_ai/services/azure_audio_to_text.py","lineNumber":77,"sourceCode":"            async_client: An existing client to use. (Optional)\n            env_file_path: Use the environment settings file as a fallback to\n                environment variables. (Optional)\n            env_file_encoding: The encoding of the environment settings file. (Optional)\n            credential: The credential to use for authentication. (Optional)\n        \"\"\"\n        try:\n            azure_openai_settings = AzureOpenAISettings(\n                env_file_path=env_file_path,\n                env_file_encoding=env_file_encoding,\n                api_key=api_key,\n                audio_to_text_deployment_name=deployment_name,\n                endpoint=endpoint,\n                base_url=base_url,\n                api_version=api_version,\n                token_endpoint=token_endpoint,\n            )\n        except ValidationError as exc:\n            raise ServiceInitializationError(f\"Invalid settings: {exc}\") from exc\n        if not azure_openai_settings.audio_to_text_deployment_name:\n            raise ServiceInitializationError(\"The Azure OpenAI audio to text deployment name is required.\")\n\n        super().__init__(\n            deployment_name=azure_openai_settings.audio_to_text_deployment_name,\n            endpoint=azure_openai_settings.endpoint,\n            base_url=azure_openai_settings.base_url,\n            api_version=azure_openai_settings.api_version,\n            service_id=service_id,\n            api_key=azure_openai_settings.api_key.get_secret_value() if azure_openai_settings.api_key else None,\n            ad_token=ad_token,\n            ad_token_provider=ad_token_provider,\n            token_endpoint=azure_openai_settings.token_endpoint,\n            default_headers=default_headers,\n            ai_model_type=OpenAIModelTypes.AUDIO_TO_TEXT,\n            client=async_client,\n            credential=credential,\n        )","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/ai/open_ai/services/azure_audio_to_text.py#L59-L95","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the full validation error in the exception message — pydantic lists each failing field and why.","Fix the specific field(s) flagged by the ValidationError (type, format, missing value).","Validate environment variables: ensure AZURE_OPENAI_ENDPOINT is a full https URL and AZURE_OPENAI_API_VERSION follows the YYYY-MM-DD format.","Pass values explicitly in the constructor to isolate which source is malformed."],"exampleFix":"// before\nservice = AzureOpenAIAudioToTextService(endpoint='my-resource', api_version='v1')\n// after\nservice = AzureOpenAIAudioToTextService(\n    endpoint='https://my-resource.openai.azure.com/',\n    api_version='2024-02-15-preview',\n    api_key='...',\n    deployment_name='whisper'\n)","handlingStrategy":"try-catch","validationCode":"def validate_azure_settings_kwargs(endpoint: str, api_version: str, api_key: str) -> None:\n    if endpoint and not endpoint.startswith('https://'):\n        raise ValueError(f'endpoint must be an https URL, got: {endpoint}')\n    if api_version:\n        import re\n        if not re.match(r'^\\d{4}-\\d{2}-\\d{2}', api_version):\n            raise ValueError(f'api_version should be YYYY-MM-DD format, got: {api_version}')\n    if not api_key:\n        raise ValueError('api_key is required')","typeGuard":"def are_azure_settings_args_valid(endpoint, api_version, api_key) -> bool:\n    import re\n    if endpoint and not endpoint.startswith('https://'):\n        return False\n    if api_version and not re.match(r'^\\d{4}-\\d{2}-\\d{2}', api_version):\n        return False\n    return bool(api_key)","tryCatchPattern":"from semantic_kernel.exceptions import ServiceInitializationError\n\ntry:\n    service = AzureOpenAIAudioToTextService(endpoint=ep, api_key=key, deployment_name=dep)\nexcept ServiceInitializationError as e:\n    print(f'Settings validation failed: {e}')\n    # fix the specific field from the error detail and retry","preventionTips":["Validate endpoint URLs start with https:// before passing to constructors.","Ensure api_version follows the YYYY-MM-DD-preview format.","Load .env files explicitly with python-dotenv before constructing services.","Pass settings explicitly during development to isolate env var issues."],"tags":["azure-openai","audio-to-text","initialization","settings","pydantic","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}