microsoft/semantic-kernel · error · ServiceInitializationError

Please provide an endpoint or a base_url

Error message

Please provide an endpoint or a base_url

What it means

Raised by AzureOpenAIConfigBase.__init__ — the shared base class for every Azure OpenAI service (chat, text, embedding, audio, image, realtime). After confirming an auth credential exists, it checks that at least one routing target was provided: either endpoint (the Azure resource URL, e.g. https://<resource>.openai.azure.com) or base_url (the full path including /openai/deployments/...). Without one, the underlying openai AsyncAzureOpenAI client cannot determine where to send requests.

Source

Thrown at python/semantic_kernel/connectors/ai/open_ai/services/azure_config_base.py:90

        merged_headers = dict(copy(default_headers)) if default_headers else {}
        if APP_INFO:
            merged_headers.update(APP_INFO)
            merged_headers = prepend_semantic_kernel_to_user_agent(merged_headers)

        if not client:
            # If the client is None, the api_key is none, the ad_token is none, and the ad_token_provider is none,
            # then we will attempt to get the ad_token using the default endpoint specified in the Azure OpenAI
            # settings.
            if not api_key and not ad_token_provider and not ad_token and token_endpoint and credential:
                ad_token = get_entra_auth_token(credential, token_endpoint)

            if not api_key and not ad_token and not ad_token_provider and not credential:
                raise ServiceInitializationError(
                    "Please provide either api_key, ad_token, ad_token_provider, credential or a client."
                )

            if not endpoint and not base_url:
                raise ServiceInitializationError("Please provide an endpoint or a base_url")

            args: dict[str, Any] = {
                "default_headers": merged_headers,
            }
            if api_version:
                args["api_version"] = api_version
            if ad_token:
                args["azure_ad_token"] = ad_token
            if ad_token_provider:
                args["azure_ad_token_provider"] = ad_token_provider
            if api_key:
                args["api_key"] = api_key
            if base_url:
                args["base_url"] = str(base_url)
            if endpoint and not base_url:
                args["azure_endpoint"] = str(endpoint)
            # TODO (eavanvalkenburg): Remove the check on model type when the package fixes: https://github.com/openai/openai-python/issues/2120
            if deployment_name and ai_model_type != OpenAIModelTypes.REALTIME:

View on GitHub (pinned to c028a0c7dc)

Solutions

  1. Set the AZURE_OPENAI_ENDPOINT environment variable to your Azure resource URL (e.g. https://myresource.openai.azure.com) or add AZURE_OPENAI_BASE_URL for the full deployment path.
  2. Pass endpoint= explicitly in the constructor call: AzureChatCompletion(deployment_name='my-model', endpoint='https://myresource.openai.azure.com', api_key='...').
  3. Ensure your .env file is discoverable — pass env_file_path='.env' or verify the working directory when the process starts.
  4. If you have a pre-configured AsyncAzureOpenAI client, pass it via async_client= to bypass endpoint resolution entirely.

Example fix

# before
service = AzureChatCompletion(
    deployment_name='gpt-4o',
    api_key=os.environ['AZURE_OPENAI_API_KEY'],
)
# after
service = AzureChatCompletion(
    deployment_name='gpt-4o',
    endpoint='https://myresource.openai.azure.com',
    api_key=os.environ['AZURE_OPENAI_API_KEY'],
)
Defensive patterns

Strategy: validation

Validate before calling

import os
from semantic_kernel.connectors.ai.open_ai.settings.azure_open_ai_settings import AzureOpenAISettings

# Validate endpoint/base_url before constructing any Azure service
settings = AzureOpenAISettings.create()
if not settings.endpoint and not settings.base_url:
    raise ValueError(
        "AZURE_OPENAI_ENDPOINT or AZURE_OPENAI_BASE_URL must be set. "
        "Found neither in environment or .env file."
    )

Try / catch

from semantic_kernel.exceptions.service_exceptions import ServiceInitializationError

try:
    service = AzureChatCompletion(
        deployment_name='gpt-4o',
        endpoint='https://myresource.openai.azure.com',
        api_key=os.environ['AZURE_OPENAI_API_KEY'],
    )
except ServiceInitializationError as e:
    if 'endpoint or a base_url' in str(e):
        # Configuration error — check env vars and .env file
        print(f'Missing Azure endpoint config: {e}')
    raise

Prevention

When it happens

Trigger: Constructing any Azure service subclass (AzureChatCompletion, AzureTextEmbedding, AzureTextToAudio, AzureRealtimeWebRTC, etc.) without passing endpoint= or base_url=, without passing a pre-built async_client, AND without AZURE_OPENAI_ENDPOINT or AZURE_OPENAI_BASE_URL in the environment or .env file. The auth check at line 84 must have already passed, so a credential (api_key / ad_token / credential) was supplied but no target URL.

Common situations: Missing or misnamed .env file; AZURE_OPENAI_ prefix typo (e.g. AZURE_OPENAI_ENDPOINT spelled AZURE_OPENAI_END_POINT); CI/CD pipeline where secrets are injected under different variable names; copy-pasting sample code without setting environment variables; .env file not loaded because env_file_path points to the wrong location.

Related errors

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