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

DashScope embedding transformation validate_environment requires an API key: if api_key is None it falls back to the DASHSCOPE_API_KEY environment variable via get_secret_str, and if that is also absent it raises ValueError telling you to set the env var or pass the key explicitly. This fails before any HTTP request is made.

Source

Thrown at litellm/llms/dashscope/embed/transformation.py:78

            # unsupported params are dropped when drop_params=True;
            # the upstream _check_valid_arg already raised UnsupportedParamsError
            # for drop_params=False before this method is called.
        return optional_params

    def validate_environment(
        self,
        headers: dict,
        model: str,
        messages: list[AllMessageValues],
        optional_params: dict,
        litellm_params: dict,
        api_key: str | None = None,
        api_base: str | 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 = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {api_key}",
        }
        return {**default_headers, **headers}

    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:
        base = api_base or get_secret_str("DASHSCOPE_API_BASE") or DEFAULT_API_BASE

View on GitHub (pinned to 6c2dcb801b)

Solutions

Export DASHSCOPE_API_KEY in the environment the process runs in: export DASHSCOPE_API_KEY=sk-...
Or pass the key explicitly: litellm.embedding(model="dashscope/...", ..., api_key=sk) / set api_key in the model's litellm_params on the proxy
If using a .env file, ensure it is loaded (litellm reads .env via dotenv only if configured) or set the var in the container/service unit
Verify with: python -c "import os; print(bool(os.environ.get('DASHSCOPE_API_KEY')))"

Example fix

# before
litellm.embedding(model="dashscope/text-embedding-v3", input=["hi"])
# ValueError: DashScope API key is required...

# after
litellm.embedding(model="dashscope/text-embedding-v3", input=["hi"], api_key=os.environ["DASHSCOPE_API_KEY"])

Defensive patterns

Strategy: validation

Validate before calling

import os, litellm
key = os.environ.get("DASHSCOPE_API_KEY")
if not key:
    raise RuntimeError("Set DASHSCOPE_API_KEY before calling dashscope embeddings")
litellm.embedding(model="dashscope/text-embedding-v3", input=["hi"], api_key=key)

Type guard

def has_dashscope_credentials(api_key: str | None) -> bool:
    import os
    return bool(api_key or os.environ.get("DASHSCOPE_API_KEY"))

Try / catch

try:
    litellm.embedding(model="dashscope/text-embedding-v3", input=texts)
except ValueError as e:
    if "DASHSCOPE_API_KEY" in str(e):
        raise ConfigError("missing dashscope credentials") from e
    raise

Prevention

Set DASHSCOPE_API_KEY in the service's environment (docker-compose env, systemd Environment=, serverless config) — not just your shell
Pass api_key explicitly in multi-tenant proxy configs so environments without the var still work
Add a startup credential check for every provider you call

When it happens

Trigger: Calling litellm.embedding with a dashscope model (e.g. text-embedding-v3 via DashScope) without api_key in the call/config and without DASHSCOPE_API_KEY exported in the environment (including the process env seen by litellm's secret resolver).

Common situations: Deployments where the env var is set in a shell but not in the service (systemd/docker/serverless); .env file not loaded; typo DASHSCOPE_APIkEY; key stored under a different name (e.g. OPENAI_API_KEY) while using DashScope models; proxy setups that strip env vars.

Related errors

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