microsoft/semantic-kernel · error · AgentInitializationException

Failed to create Azure OpenAI settings

Error message

Failed to create Azure OpenAI settings: {exc}

What it means

While constructing the AsyncAzureOpenAI client, the agent builds an AzureOpenAISettings object from supplied args/env. If pydantic validation of those settings fails, the ValidationError is wrapped as AgentInitializationException("Failed to create Azure OpenAI settings"). The wrapped error text enumerates which fields failed validation.

Solutions

  1. Read the wrapped ValidationError in exc.__cause__ to see exactly which settings field(s) failed.
  2. Correct the offending env var or constructor argument (URL format, api_version string, file path).
  3. Ensure the .env file exists at env_file_path and uses the specified env_file_encoding.
  4. Validate settings explicitly with AzureOpenAISettings() in isolation to surface errors before constructing the agent.

Example fix

// before
AzureOpenAIAssistantAgent(..., env_file_path="missing.env")
# -> Failed to create Azure OpenAI settings

// after
AzureOpenAIAssistantAgent(..., env_file_path=".env")  # valid file with AZURE_OPENAI_* vars
Defensive patterns

Strategy: try-catch

Validate before calling

from semantic_kernel.connectors.ai.open_ai import AzureOpenAISettings

def settings_build_ok(**kwargs) -> bool:
    try:
        AzureOpenAISettings(**kwargs)
        return True
    except Exception:
        return False

Try / catch

from semantic_kernel.exceptions import AgentInitializationException

try:
    agent = AzureOpenAIAssistantAgent(...)
except AgentInitializationException as e:
    cause = e.__cause__  # pydantic ValidationError with field details
    logger.error("settings invalid: %s", cause)

Prevention

When it happens

Trigger: Calling the agent/client factory with arguments or environment variables that fail AzureOpenAISettings validation — e.g. malformed endpoint URL, invalid api_version format, unreadable env_file_path, or a field whose value violates its type/constraint.

Common situations: Missing or malformed AZURE_OPENAI_* env vars; pointing env_file_path at a non-existent .env; supplying api_version as a non-string or unsupported value; endpoint not a valid URL; env_file_encoding mismatch.

Related errors

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

Appendix: source

Thrown at python/semantic_kernel/agents/open_ai/azure_assistant_agent.py:99

            credential: The credential to use for authentication.
            kwargs: Additional keyword arguments

        Returns:
            An Azure OpenAI client instance and the configured deployment name (model)
        """
        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_scope,
            )
        except ValidationError as exc:
            raise AgentInitializationException(f"Failed to create Azure OpenAI settings: {exc}") from exc

        if (
            azure_openai_settings.api_key is None
            and ad_token_provider is None
            and ad_token is None
            and azure_openai_settings.token_endpoint
            and credential
        ):
            ad_token = get_entra_auth_token(credential, azure_openai_settings.token_endpoint)

        # If we still have no credentials, we can't proceed
        if not azure_openai_settings.api_key and not ad_token and not ad_token_provider and not credential:
            raise AgentInitializationException(
                "Please provide either an api_key, ad_token, ad_token_provider or credential for authentication."
            )

        merged_headers = dict(copy(default_headers)) if default_headers else {}
        if default_headers:

View on GitHub (pinned to c028a0c7dc)