openai/openai-python · error · ValueError

Unable to handle auth

Error message

Unable to handle auth

What it means

An internal invariant in _prepare_options: the request had neither an api-key header, nor an api-key-bearing client, nor an Authorization header. The comment says it 'should never be hit', so hitting it indicates corrupted client state or a custom subclass interfering with auth header generation.

Source

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

            self._refresh_api_key()

        headers: dict[str, str | Omit] = {**options.headers} if is_given(options.headers) else {}

        options = model_copy(options)
        options.headers = headers

        azure_ad_token = self._get_azure_ad_token()
        if azure_ad_token is not None:
            if not _has_header(headers, "Authorization"):
                headers["Authorization"] = f"Bearer {azure_ad_token}"
        elif self.api_key and self.api_key != API_KEY_SENTINEL:
            if not _has_header(headers, "api-key"):
                headers["api-key"] = self.api_key
        elif _has_auth_header(headers) or _has_auth_header(self.default_headers):
            pass
        else:
            # should never be hit
            raise ValueError("Unable to handle auth")

        return options

    def _configure_realtime(self, model: str, extra_query: Query) -> tuple[httpx2.URL, dict[str, str]]:
        auth_headers = {}
        query = {
            **extra_query,
            "api-version": self._api_version,
            "deployment": self._azure_deployment or model,
        }
        if self.api_key and self.api_key != "<missing API key>":
            auth_headers = {"api-key": self.api_key}
        else:
            token = self._get_azure_ad_token()
            if token:
                auth_headers = {"Authorization": f"Bearer {token}"}

        if self.websocket_base_url is not None:

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Avoid mutating default_headers to strip Authorization/api-key; construct a new client instead
2. If subclassing, ensure _auth_headers/_prepare_options overrides preserve the contract
3. Report as a bug if reproducible with the unmodified client

try:
    client.chat.completions.create(...)
except ValueError as e:
    if str(e) == "Unable to handle auth":
        rebuild_client_with_fresh_auth()
    raise

When it happens

Trigger: Mutating client.auth/default_headers after construction to remove auth, subclassing AzureOpenAI and overriding _prepare_options/_auth_headers incorrectly, or a custom api_key provider returning a value that bypasses the api-key branch.

Common situations: Essentially unreachable in normal use; appears only with subclasses or direct header manipulation.

Related errors

• 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}
• X.509 workload identity is not supported by Azure clients
• Missing credentials. Please pass one of `api_key`, `azure_ad

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