openai/openai-python · error · ValueError

base_url and azure_endpoint are mutually exclusive

Error message

base_url and azure_endpoint are mutually exclusive

What it means

AzureOpenAI cannot derive its URL from two conflicting sources. Supplying both base_url and azure_endpoint is ambiguous (they overlap in purpose), so the constructor raises ValueError immediately.

Solutions

  1. Remove one of the two arguments — keep azure_endpoint for standard Azure usage
  2. If you truly need a custom full URL, pass only base_url and drop azure_endpoint

Example fix

# before
client = AzureOpenAI(base_url="https://res.openai.azure.com/openai", azure_endpoint="https://res.openai.azure.com")
# after
client = AzureOpenAI(azure_endpoint="https://res.openai.azure.com")
Defensive patterns

Strategy: validation

Validate before calling

if base_url and azure_endpoint:
    raise ValueError("pass only one of base_url or azure_endpoint")

Prevention

When it happens

Trigger: Calling AzureOpenAI(base_url=..., azure_endpoint=...) in the same constructor; often happens when base_url is set from a config object while azure_endpoint is hardcoded.

Common situations: Copying sample code that sets base_url while env/config also sets azure_endpoint; refactoring from OpenAI to AzureOpenAI and leaving base_url in place.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/140c61f734ef647c. Report an issue: GitHub.

Appendix: source

Thrown at src/openai/lib/azure.py:334

        else:
            default_query = {**default_query, "api-version": api_version}

        if base_url is None:
            if azure_endpoint is None:
                azure_endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")

            if azure_endpoint is None:
                raise ValueError(
                    "Must provide one of the `base_url` or `azure_endpoint` arguments, or the `AZURE_OPENAI_ENDPOINT` environment variable"
                )

            if azure_deployment is not None:
                base_url = f"{azure_endpoint.rstrip('/')}/openai/deployments/{azure_deployment}"
            else:
                base_url = f"{azure_endpoint.rstrip('/')}/openai"
        else:
            if azure_endpoint is not None:
                raise ValueError("base_url and azure_endpoint are mutually exclusive")

        if api_key is None:
            # define a sentinel value to avoid any typing issues
            api_key = API_KEY_SENTINEL

        super().__init__(
            api_key=api_key,
            admin_api_key=admin_api_key,
            organization=organization,
            project=project,
            webhook_secret=webhook_secret,
            base_url=base_url,
            timeout=timeout,
            max_retries=max_retries,
            default_headers=default_headers,
            default_query=default_query,
            http_client=http_client,
            websocket_base_url=websocket_base_url,

View on GitHub (pinned to 9917c6e28e)