BerriAI/litellm · error · ValueError

MODELSCOPE_API_KEY is not set. Please set it via environment

Error message

MODELSCOPE_API_KEY is not set. Please set it via environment variable or pass api_key parameter.

What it means

Raised by litellm's ModelScope image generation transformer when no API key can be resolved: the api_key parameter is falsy and the MODELSCOPE_API_KEY environment variable is unset. It is a pre-flight configuration error raised in validate_environment before any request is sent.

Source

Thrown at litellm/llms/modelscope/image_generation/transformation.py:111

    @override
    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:
        """
        Validate environment and set up headers for ModelScope.
        """
        final_api_key: Final[str | None] = api_key or get_secret_str("MODELSCOPE_API_KEY")

        if not final_api_key:
            raise ValueError(
                "MODELSCOPE_API_KEY is not set. Please set it via environment variable or pass api_key parameter."
            )

        default_headers: Final = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {final_api_key}",
        }

        headers = {**headers, **default_headers}
        return headers

    def transform_image_generation_request(
        self,
        model: str,
        prompt: str,
        optional_params: dict,
        litellm_params: dict,
        headers: dict,

View on GitHub (pinned to 6c2dcb801b)

Solutions

export MODELSCOPE_API_KEY=<your key> (from modelscope.cn -> access tokens) and restart the process.
Or pass api_key directly to the litellm.image_generation() call.
For litellm proxy, configure the key under the model deployment's litellm_params.
Confirm the variable name is exactly MODELSCOPE_API_KEY with no trailing whitespace.

Example fix

# before
img = litellm.image_generation(model="modelscope/wanx-v1", prompt="a cat")

# after
img = litellm.image_generation(
    model="modelscope/wanx-v1",
    prompt="a cat",
    api_key=os.environ["MODELSCOPE_API_KEY"],
)

Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.getenv("MODELSCOPE_API_KEY"):
    raise RuntimeError("MODELSCOPE_API_KEY not set; get one from modelscope.cn")

Try / catch

try:
    img = litellm.image_generation(model="modelscope/wanx-v1", prompt=p)
except ValueError as e:
    if "MODELSCOPE_API_KEY is not set" in str(e):
        raise RuntimeError("Config error: MODELSCOPE_API_KEY missing") from e
    raise

Prevention

Add env var presence checks for every provider you enable in a startup preflight.
Store the key in a secret manager; inject at deploy time.
Document required env vars per provider in the service README.

When it happens

Trigger: Calling litellm.image_generation() with a modelscope/* model without api_key and without MODELSCOPE_API_KEY exported in the shell/process running litellm.

Common situations: Missing export in shell profile, container image built without the secret, CI env not injected, or the key stored under a different variable name.

Related errors

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