BerriAI/litellm · error · ValueError

DashScope API key is required. Set 'DASHSCOPE_API_KEY' env v

Error message

DashScope API key is required. Set 'DASHSCOPE_API_KEY' env var or pass api_key explicitly.

What it means

Raised by the DashScope rerank transformer when no API key can be resolved: the api_key argument is None and the DASHSCOPE_API_KEY secret/env lookup also returns None. Thrown before any network call, as a ValueError from validate_environment.

Source

Thrown at litellm/llms/dashscope/rerank/transformation.py:92

            return cleaned

        if cleaned.endswith("/v1"):
            return f"{cleaned}/reranks"

        # Unknown base: append /reranks rather than silently ignoring the caller's api_base.
        return f"{cleaned}/reranks"

    def validate_environment(
        self,
        headers: dict,
        model: str,
        api_key: str | None = None,
        optional_params: dict | None = None,
    ) -> dict:
        if api_key is None:
            api_key = get_secret_str("DASHSCOPE_API_KEY")
        if api_key is None:
            raise ValueError(
                "DashScope API key is required. Set 'DASHSCOPE_API_KEY' env var or pass api_key explicitly."
            )

        default_headers: Final = {
            "Authorization": f"Bearer {api_key}",
            "accept": "application/json",
            "content-type": "application/json",
        }
        return {**default_headers, **headers}

    def get_supported_cohere_rerank_params(self, model: str) -> list:
        return ["query", "documents", "top_n", "return_documents"]

    def map_cohere_rerank_params(
        self,
        non_default_params: dict | None,
        model: str,
        drop_params: bool,

View on GitHub (pinned to 6c2dcb801b)

Solutions

Export DASHSCOPE_API_KEY=sk-... in the process environment
Or pass api_key explicitly to the rerank call
If using LiteLLM proxy, add the key to the model's litellm_params in the config YAML
Confirm the env var is visible inside the actual runtime (docker exec / kubectl exec)

Example fix

# before
resp = litellm.rerank(model="dashscope/gte-rerank", query="q", documents=docs)

# after
resp = litellm.rerank(model="dashscope/gte-rerank", query="q", documents=docs, api_key=os.environ["DASHSCOPE_API_KEY"])

Defensive patterns

Strategy: validation

Validate before calling

if not (api_key or os.getenv("DASHSCOPE_API_KEY")):
    raise RuntimeError("Set DASHSCOPE_API_KEY before calling DashScope rerank")

Try / catch

try:
    resp = litellm.rerank(model=m, query=q, documents=docs)
except ValueError as e:
    if "DASHSCOPE_API_KEY" in str(e):
        raise ConfigError(str(e)) from e
    raise

Prevention

Centralize provider key checks in one preflight function called before any dashscope request
In LiteLLM proxy, always set the key in litellm_params so the env fallback is never exercised

When it happens

Trigger: Calling litellm.rerank() with a DashScope rerank model (e.g. gte-rerank / qwen3-rerank) without an api_key parameter and without DASHSCOPE_API_KEY in the environment or secret manager.

Common situations: Rerank integration added to a RAG pipeline where only OPENAI_API_KEY was configured; env var set in the shell but not in the systemd/docker service unit; secret stored under a different key name in LiteLLM's secret manager.

Related errors

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