BerriAI/litellm · error · WatsonXAIError

Error: Watsonx URL not set. Set WATSONX_API_BASE in environm

Error message

Error: Watsonx URL not set. Set WATSONX_API_BASE in environment variables or pass in as parameter - 'api_base='.

What it means

WatsonXAIEndpointImplementer._get_base_url resolves the service URL from the api_base argument or env chain WATSONX_API_BASE / WATSONX_URL / WX_URL / WML_URL. If everything is empty it raises WatsonXAIError (401) telling you to set WATSONX_API_BASE. Note this guards the watsonx.ai REST endpoint path, not the IAM endpoint.

Source

Thrown at litellm/llms/watsonx/common_utils.py:270

        elif zen_api_key:
            headers["Authorization"] = f"ZenApiKey {zen_api_key}"
        else:
            token = _generate_watsonx_token(api_key=api_key, token=token)
            # build auth headers
            headers["Authorization"] = f"Bearer {token}"
        return {**default_headers, **headers}

    def _get_base_url(self, api_base: str | None) -> str:
        url: Final = (
            api_base
            or get_secret_str("WATSONX_API_BASE")  # consistent with 'AZURE_API_BASE'
            or get_secret_str("WATSONX_URL")
            or get_secret_str("WX_URL")
            or get_secret_str("WML_URL")
        )

        if url is None:
            raise WatsonXAIError(
                status_code=401,
                message="Error: Watsonx URL not set. Set WATSONX_API_BASE in environment variables or pass in as parameter - 'api_base='.",
            )
        return url

    def _add_api_version_to_url(self, url: str, api_version: str | None) -> str:
        api_version = api_version or litellm.WATSONX_DEFAULT_API_VERSION
        url = url + f"?version={api_version}"

        return url

    def get_error_class(self, error_message: str, status_code: int, headers: dict | httpx.Headers) -> BaseLLMException:
        return WatsonXAIError(status_code=status_code, message=error_message, headers=headers)

    @staticmethod
    def get_watsonx_credentials(optional_params: dict, api_key: str | None, api_base: str | None) -> WatsonXCredentials:
        api_key = (
            api_key

View on GitHub (pinned to 77b7c6c40c)

Solutions

export WATSONX_APIBASE is wrong - use export WATSONX_API_BASE=https://us-south.ml.cloud.ibm.com (or WATSONX_URL / WX_URL / WML_URL).
Or pass api_base="https://us-south.ml.cloud.ibm.com" to the call.
Confirm the region host matches your provisioned region (eu-de, jp-tok, etc.).
Add a startup assertion for the env var in deployment scripts.

Example fix

# before
resp = litellm.completion(model="watsonx/meta-llama/llama-3-8b-instruct", messages=msgs)
# -> WatsonXAIError: Watsonx URL not set...

# after
import os
os.environ["WATSONX_API_BASE"] = "https://us-south.ml.cloud.ibm.com"
resp = litellm.completion(model="watsonx/meta-llama/llama-3-8b-instruct", messages=msgs)

Defensive patterns

Strategy: validation

Validate before calling

import os

WX_BASE = (
    os.getenv("WATSONX_API_BASE")
    or os.getenv("WATSONX_URL")
    or os.getenv("WX_URL")
    or os.getenv("WML_URL")
)
if not WX_BASE:
    raise RuntimeError("Set WATSONX_API_BASE (e.g. https://us-south.ml.cloud.ibm.com)")
resp = litellm.completion(model="watsonx/...", messages=msgs, api_base=WX_BASE)

Type guard

const hasWatsonxBase = (env: Record<string, string | undefined>): boolean =>
  Boolean(env.WATSONX_API_BASE ?? env.WATSONX_URL ?? env.WX_URL ?? env.WML_URL);

Try / catch

from litellm.llms.watsonx.common_utils import WatsonXAIError

try:
    resp = litellm.completion(model="watsonx/...", messages=msgs)
except WatsonXAIError as e:
    if "Watsonx URL not set" in e.message:
        raise RuntimeError("Set WATSONX_API_BASE to your WatsonX region host") from e
    raise

Prevention

Note the exact name: WATSONX_API_BASE (not WATSONX_APIBASE).
Match the host to your provisioned region (us-south, eu-de, ...).
Include the URL in the same config bootstrap that sets the API key and project id.

When it happens

Trigger: Calling watsonx completion/embedding/transcription without api_base and with none of the four URL env vars set; URLs defined only in a config file the process does not read; env var set to an empty string.

Common situations: Fresh onboarding to litellm+WatsonX (key and project set but URL forgotten); Cloud Foundry style deployments where VCAP provides the URL but code does not map it; migrating from WML_URL conventions on older clusters.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/fe16731392e35447. Report an issue: GitHub.