{"record":{"id":"fe16731392e35447","repo":"BerriAI/litellm","slug":"error-watsonx-url-not-set-set-watsonx-api-base-i","errorCode":null,"errorMessage":"Error: Watsonx URL not set. Set WATSONX_API_BASE in environment variables or pass in as parameter - 'api_base='.","messagePattern":"Error: Watsonx URL not set\\. Set WATSONX_API_BASE in environment variables or pass in as parameter - 'api_base='\\.","errorType":"exception","errorClass":"WatsonXAIError","httpStatus":401,"severity":"error","filePath":"litellm/llms/watsonx/common_utils.py","lineNumber":270,"sourceCode":"        elif zen_api_key:\n            headers[\"Authorization\"] = f\"ZenApiKey {zen_api_key}\"\n        else:\n            token = _generate_watsonx_token(api_key=api_key, token=token)\n            # build auth headers\n            headers[\"Authorization\"] = f\"Bearer {token}\"\n        return {**default_headers, **headers}\n\n    def _get_base_url(self, api_base: str | None) -> str:\n        url: Final = (\n            api_base\n            or get_secret_str(\"WATSONX_API_BASE\")  # consistent with 'AZURE_API_BASE'\n            or get_secret_str(\"WATSONX_URL\")\n            or get_secret_str(\"WX_URL\")\n            or get_secret_str(\"WML_URL\")\n        )\n\n        if url is None:\n            raise WatsonXAIError(\n                status_code=401,\n                message=\"Error: Watsonx URL not set. Set WATSONX_API_BASE in environment variables or pass in as parameter - 'api_base='.\",\n            )\n        return url\n\n    def _add_api_version_to_url(self, url: str, api_version: str | None) -> str:\n        api_version = api_version or litellm.WATSONX_DEFAULT_API_VERSION\n        url = url + f\"?version={api_version}\"\n\n        return url\n\n    def get_error_class(self, error_message: str, status_code: int, headers: dict | httpx.Headers) -> BaseLLMException:\n        return WatsonXAIError(status_code=status_code, message=error_message, headers=headers)\n\n    @staticmethod\n    def get_watsonx_credentials(optional_params: dict, api_key: str | None, api_base: str | None) -> WatsonXCredentials:\n        api_key = (\n            api_key","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/llms/watsonx/common_utils.py#L252-L288","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nresp = litellm.completion(model=\"watsonx/meta-llama/llama-3-8b-instruct\", messages=msgs)\n# -> WatsonXAIError: Watsonx URL not set...\n\n# after\nimport os\nos.environ[\"WATSONX_API_BASE\"] = \"https://us-south.ml.cloud.ibm.com\"\nresp = litellm.completion(model=\"watsonx/meta-llama/llama-3-8b-instruct\", messages=msgs)","handlingStrategy":"validation","validationCode":"import os\n\nWX_BASE = (\n    os.getenv(\"WATSONX_API_BASE\")\n    or os.getenv(\"WATSONX_URL\")\n    or os.getenv(\"WX_URL\")\n    or os.getenv(\"WML_URL\")\n)\nif not WX_BASE:\n    raise RuntimeError(\"Set WATSONX_API_BASE (e.g. https://us-south.ml.cloud.ibm.com)\")\nresp = litellm.completion(model=\"watsonx/...\", messages=msgs, api_base=WX_BASE)","typeGuard":"const hasWatsonxBase = (env: Record<string, string | undefined>): boolean =>\n  Boolean(env.WATSONX_API_BASE ?? env.WATSONX_URL ?? env.WX_URL ?? env.WML_URL);","tryCatchPattern":"from litellm.llms.watsonx.common_utils import WatsonXAIError\n\ntry:\n    resp = litellm.completion(model=\"watsonx/...\", messages=msgs)\nexcept WatsonXAIError as e:\n    if \"Watsonx URL not set\" in e.message:\n        raise RuntimeError(\"Set WATSONX_API_BASE to your WatsonX region host\") from e\n    raise","preventionTips":["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."],"tags":["watsonx","api-base","url-configuration","environment-variable","litellm"],"backgroundTag":"missing-api-base-url","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}