microsoft/semantic-kernel · error · ServiceInitializationError

Failed to create OpenAI settings.

Error message

Failed to create OpenAI settings.

What it means

Raised by AzureRealtimeWebsocket.__init__ when AzureOpenAISettings construction throws a pydantic ValidationError. The settings class (a pydantic-settings BaseSettings subclass) validates fields like endpoint (must be HttpsUrl), base_url (must be Url), api_key (must be SecretStr), and api_version (must be str). If any field receives a value that fails type coercion, pydantic raises ValidationError which this code wraps as ServiceInitializationError.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/azure_realtime.py:124

                kernel (Kernel): the kernel to use for function calls
                plugins (list[object] or dict[str, object]): the plugins to use for function calls
                settings (OpenAIRealtimeExecutionSettings): the settings to use for the session
                chat_history (ChatHistory): the chat history to use for the session
                Otherwise they can also be passed to the context manager.
        """
        try:
            azure_openai_settings = AzureOpenAISettings(
                api_key=api_key,
                base_url=base_url,
                endpoint=endpoint,
                realtime_deployment_name=deployment_name,
                api_version=api_version,
                token_endpoint=token_endpoint,
                env_file_path=env_file_path,
                env_file_encoding=env_file_encoding,
            )
        except ValidationError as ex:
            raise ServiceInitializationError("Failed to create OpenAI settings.", ex) from ex
        if not azure_openai_settings.realtime_deployment_name:
            raise ServiceInitializationError("The OpenAI realtime model ID is required.")
        super().__init__(
            api_key=azure_openai_settings.api_key.get_secret_value() if azure_openai_settings.api_key else None,
            audio_output_callback=audio_output_callback,
            deployment_name=azure_openai_settings.realtime_deployment_name,
            endpoint=azure_openai_settings.endpoint,
            base_url=azure_openai_settings.base_url,
            api_version=azure_openai_settings.api_version,
            ad_token=ad_token,
            ad_token_provider=ad_token_provider,
            token_endpoint=azure_openai_settings.token_endpoint,
            ai_model_type=OpenAIModelTypes.REALTIME,
            service_id=service_id,
            default_headers=default_headers,
            client=async_client,
            websocket_base_url=websocket_base_url,
            credential=credential,

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Inspect the chained ValidationError (passed as the second argument) — it lists each invalid field and the expected type.
2. Ensure endpoint uses the https:// scheme and a fully-qualified URL: 'https://myresource.openai.azure.com'.
3. If using a .env file, quote values containing special characters and verify the file is valid dotenv syntax.
4. Pass api_version as a plain string (e.g. '2024-10-01-preview'), not a date object or None where the field requires str.

Example fix

# before
service = AzureRealtimeWebsocket(
    deployment_name='gpt-4o-realtime',
    endpoint='myresource.openai.azure.com',  # missing scheme
    api_key='...',
)
# after
service = AzureRealtimeWebsocket(
    deployment_name='gpt-4o-realtime',
    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}://')
    if not parsed.hostname or 'openai.azure.com' not in parsed.hostname:
        raise ValueError(f'endpoint must be an Azure OpenAI resource URL, got {endpoint}')
    return endpoint

# Use before constructing AzureRealtimeWebsocket
validate_azure_endpoint(os.environ.get('AZURE_OPENAI_ENDPOINT'))

from semantic_kernel.exceptions.service_exceptions import ServiceInitializationError

try:
    service = AzureRealtimeWebsocket(
        deployment_name='gpt-4o-realtime',
        endpoint='https://myresource.openai.azure.com',
        api_key='...',
    )
except ServiceInitializationError as e:
    cause = e.__cause__  # the original ValidationError
    if cause:
        print(f'Settings validation failed: {cause}')
    raise

When it happens

Trigger: Constructing AzureRealtimeWebsocket with an endpoint value that is not a valid HTTPS URL (e.g. 'http://...' or a bare hostname), passing api_version as a non-string type, or having an AZURE_OPENAI_ENDPOINT environment variable containing a malformed URL. The env_file_path pointing to an unreadable file with invalid syntax can also trigger it.

Common situations: Passing endpoint='http://myresource.openai.azure.com' (http instead of https); passing a bare hostname without the scheme; .env file with unquoted special characters that corrupt the endpoint value; upgrading semantic_kernel and the endpoint field type changed from str to HttpsUrl.

Related errors

• The OpenAI realtime model ID is required.
• Invalid settings: {ex}
• Invalid settings: {exc}
• Invalid settings: {exc}
• Invalid settings: {exc}

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