What causes "api_base is required" in BerriAI/litellm?

Set COHERE_API_BASE=https://api.cohere.com/compat/v1 (OpenAI-compat path) or pass api_base on the call containing the complete URL.

BerriAI/litellm · error · ValueError

api_base is required

Error message

api_base is required

What it means

Cohere v2's get_complete_url deliberately does not append any path — it expects api_base to already contain the full URL (including /v2/chat or /compat/v1/chat). If api_base is None at this point, it raises ValueError('api_base is required') rather than defaulting, because there is no safe default path to append. This differs from most providers where api_base is optional.

Source

Thrown at litellm/llms/cohere/chat/v2_transformation.py:285

            sync_stream=sync_stream,
            json_mode=json_mode,
        )

    def get_complete_url(
        self,
        api_base: str | None,
        api_key: str | None,
        model: str,
        optional_params: dict,
        litellm_params: dict,
        stream: bool | None = None,
    ) -> str:
        """
        Get the complete URL for Cohere v2 chat completion.
        The api_base should already include the full path.
        """
        if api_base is None:
            raise ValueError("api_base is required")
        return api_base

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

    def _translate_citations_to_openai_annotations(self, citations: list[dict]) -> list[ChatCompletionAnnotation]:
        """
        Transform Cohere citations to OpenAI annotations format.

        Creates separate annotations for each source in a citation, allowing multiple
        annotations with the same start/end index if they reference different sources.

        Args:
            citations: List of Cohere citation objects with format:
                {
                    "start": int,
                    "end": int,
                    "text": str,

View on GitHub (pinned to 6c2dcb801b)

Solutions

Set COHERE_API_BASE=https://api.cohere.com/compat/v1 (OpenAI-compat path) or pass api_base on the call containing the complete URL.
Audit proxy/router config: remove api_base: null / empty entries for cohere deployments so defaults apply.
Upgrade litellm if the default-URL seeding for v2 regressed in your version.
Verify with a plain litellm.completion call outside the proxy to isolate where api_base becomes None.

Example fix

# before (router config nulls the base)
# deployment: {model: cohere/command-r-plus, api_base: null}

# after
# deployment: {model: cohere/command-r-plus}
# or explicitly:
response = litellm.completion(
    model="cohere/command-r-plus", messages=[...],
    api_base="https://api.cohere.com/compat/v1",
)

Defensive patterns

Strategy: validation

Validate before calling

import os

COHERE_BASE = os.environ.get("COHERE_API_BASE") or "https://api.cohere.com/compat/v1"
assert COHERE_BASE.startswith("https://"), "cohere api_base must be a full URL"

Type guard

from typing import Optional

def has_resolved_api_base(api_base: Optional[str]) -> bool:
    """True when api_base is usable for cohere v2 (full URL required)."""
    return isinstance(api_base, str) and api_base.startswith(("http://", "https://"))

Try / catch

try:
    resp = litellm.completion(model="cohere/command-r-plus", messages=msgs)
except ValueError as e:
    if "api_base is required" in str(e):
        resp = litellm.completion(
            model="cohere/command-r-plus", messages=msgs,
            api_base="https://api.cohere.com/compat/v1",
        )
    else:
        raise

Prevention

Never write api_base: null for cohere entries in proxy/router configs — omit the key entirely.
Default COHERE_API_BASE explicitly in your environment so resolution never yields None.
Unit-test your router config against each provider with a minimal call.

When it happens

Trigger: Calling a cohere/ model through the v2 transformation with api_base unset — typically when the caller or a custom router/proxy config explicitly passes api_base=None, or a preceding URL-resolution step failed to seed the default COHERE_API_BASE. The v2 handler requires a resolved base, normally supplied from COHERE_API_BASE env or litellm defaults.

Common situations: Custom LLM routers or LiteLLM proxy configs that pass api_base: null entries; overriding cohere deployment config and accidentally nulling the base; library version regressions where the default api_base wiring changed.

Related errors

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/74c1873d2cf0e673. Report an issue: GitHub.