openai/openai-python · critical · ValueError

Must provide either the `api_version` argument or the `OPENA

Error message

Must provide either the `api_version` argument or the `OPENAI_API_VERSION` environment variable

What it means

AzureOpenAI needs an API version to build request URLs and the default api-version query param. If neither the api_version constructor argument nor the OPENAI_API_VERSION environment variable is present, construction raises ValueError.

Source

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

                Not supported with Assistants APIs.
        """
        if is_x509_workload_identity(workload_identity):
            raise OpenAIError("X.509 workload identity is not supported by Azure clients")

        api_key, azure_ad_token, azure_ad_token_provider = _resolve_azure_auth(
            api_key, azure_ad_token, azure_ad_token_provider
        )

        if _enforce_credentials and api_key is None and azure_ad_token is None and azure_ad_token_provider is None:
            raise OpenAIError(
                "Missing credentials. Please pass one of `api_key`, `azure_ad_token`, `azure_ad_token_provider`, or the `AZURE_OPENAI_API_KEY` or `AZURE_OPENAI_AD_TOKEN` environment variables."
            )

        if api_version is None:
            api_version = os.environ.get("OPENAI_API_VERSION")

        if api_version is None:
            raise ValueError(
                "Must provide either the `api_version` argument or the `OPENAI_API_VERSION` environment variable"
            )

        if default_query is None:
            default_query = {"api-version": api_version}
        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:

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Pass api_version explicitly: AzureOpenAI(api_version='2024-10-21', ...)
2. Or set OPENAI_API_VERSION in the process environment
3. Use a supported stable date-version from the Azure OpenAI API reference for the features you use

Example fix

# before
client = AzureOpenAI(azure_endpoint=..., api_key=...)
# after
client = AzureOpenAI(azure_endpoint=..., api_key=..., api_version="2024-10-21")

api_version = os.environ.get("OPENAI_API_VERSION") or "2024-10-21"
client = AzureOpenAI(api_version=api_version, ...)

try:
    client = AzureOpenAI(...)
except ValueError as e:
    if "api_version" in str(e):
        client = AzureOpenAI(api_version="2024-10-21", ...)
    else:
        raise

When it happens

Trigger: new AzureOpenAI() without api_version and without OPENAI_API_VERSION exported (e.g. fresh container, CI runner, or notebook).

Common situations: Works locally (var set in shell) but fails in Docker/cron/CI; upgrading from older SDK versions that had a default; typos like OPENAI_APIVERSION.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• X.509 workload identity is not supported by Azure clients
• Missing credentials. Please pass one of `api_key`, `azure_ad
• Failed to fetch Azure subject token from IMDS: HTTP {respons
• Azure IMDS response did not include an access_token
• Failed to fetch Azure subject token from IMDS: {e}

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