openai/openai-python · error · ValueError

The `data_residency` and `websocket_base_url` arguments are

Error message

The `data_residency` and `websocket_base_url` arguments are mutually exclusive

What it means

resolve_data_residency raises ValueError when `data_residency` is combined with `websocket_base_url`. A named residency fixes both HTTP and WebSocket endpoints, so supplying a separate WebSocket URL is contradictory and rejected before the client is built.

Source

Thrown at src/openai/_data_residency.py:35

    "eu": "https://eu.api.openai.com/v1",
    "ae": "https://ae.api.openai.com/v1",
}


def resolve_data_residency(
    data_residency: DataResidency | None,
    base_url: str | httpx2.URL | None | NotGiven,
    *,
    provider: object | None = None,
    websocket_base_url: str | httpx2.URL | None = None,
) -> str | httpx2.URL | None:
    """Resolve a named endpoint before inherited or environment options are applied."""
    if data_residency is None:
        return None if isinstance(base_url, NotGiven) else base_url
    if not isinstance(base_url, NotGiven):
        raise ValueError("The `data_residency` and `base_url` arguments are mutually exclusive")
    if websocket_base_url is not None:
        raise ValueError("The `data_residency` and `websocket_base_url` arguments are mutually exclusive")
    if provider is not None:
        raise OpenAIError("The `data_residency` and `provider` arguments are mutually exclusive")
    if not isinstance(cast(object, data_residency), str) or data_residency not in _DATA_RESIDENCY_BASE_URLS:
        raise ValueError("Invalid `data_residency`; expected one of 'global', 'us', 'eu', or 'ae'")
    return _DATA_RESIDENCY_BASE_URLS[data_residency]

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Remove websocket_base_url and rely on data_residency to derive both endpoints.
2. If a custom WebSocket endpoint is required, drop data_residency and set base_url/websocket_base_url explicitly to the desired region's URLs.

Example fix

# before
client = OpenAI(data_residency="eu", websocket_base_url="wss://eu.example.com/v1")

# after
client = OpenAI(data_residency="eu")

def build_endpoints(data_residency=None, websocket_base_url=None):
    if data_residency is not None and websocket_base_url is not None:
        raise ValueError("data_residency already defines the websocket URL")
    return data_residency, websocket_base_url

When it happens

Trigger: OpenAI(data_residency="us", websocket_base_url="wss://...") or client.copy(data_residency=..., websocket_base_url=...) with websocket_base_url not None.

Common situations: Enabling Realtime/WebSocket features with a previously customized websocket_base_url, then adding data_residency for compliance; config templates that always set both endpoint knobs.

Related errors

• The `data_residency` and `base_url` arguments are mutually e
• The `data_residency` and `provider` arguments are mutually e
• Invalid `http_client` argument; Expected an instance of `htt
• `provider` cannot be combined with top-level {formatted}. Mo
• Missing credentials. Please pass an `api_key`, `workload_ide

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