BerriAI/litellm · error · ValueError

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

Error message

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

What it means

The DashScope rerank transformer's validate_environment refuses to build request headers without credentials: it first checks the api_key argument, then falls back to get_secret_str('DASHSCOPE_API_KEY'); if both are None it raises this ValueError. No HTTP request is made — the failure is entirely local configuration.

Solutions

export DASHSCOPE_API_KEY=sk-... in the environment that actually runs the rerank call
Or pass api_key explicitly: litellm.rerank(..., api_key='sk-...')
In the LiteLLM proxy, add DASHSCOPE_API_KEY to the dashscope rerank deployment config
Fail fast at startup by asserting the env var exists before serving traffic

Example fix

# before
result = litellm.rerank(model='dashscope/gte-rerank', query='q', documents=['a', 'b'])  # ValueError

# after
result = litellm.rerank(
    model='dashscope/gte-rerank',
    query='q',
    documents=['a', 'b'],
    api_key=os.environ['DASHSCOPE_API_KEY'],
)

Defensive patterns

Strategy: validation

Validate before calling

import os

if not os.getenv('DASHSCOPE_API_KEY'):
    raise RuntimeError('Set DASHSCOPE_API_KEY before enabling the dashscope reranker')

Try / catch

try:
    result = litellm.rerank(model='dashscope/gte-rerank', query=q, documents=docs)
except ValueError as e:
    if 'DASHSCOPE_API_KEY' in str(e):
        raise ConfigError('DashScope key not configured') from e
    raise

Prevention

Assert provider env vars at startup in every worker that can issue rerank calls
Centralize credential loading in one module so rerank/chat/embedding paths share the same check

When it happens

Trigger: litellm.rerank(model='dashscope/gte-rerank-...', query=..., documents=[...]) with no api_key argument and DASHSCOPE_API_KEY absent from the environment (fresh shell, CI job, container, or proxy deployment missing the key).

Common situations: Key configured for chat models but rerank call path runs in a separate worker without env; dotenv loaded after import in some code paths; key present under a different name (e.g. DASHSCOPE_TOKEN).

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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

Appendix: 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 77b7c6c40c)