BerriAI/litellm · error · ValueError

Missing API key for Volcengine. Set ARK_API_KEY or VOLCENGIN

Error message

Missing API key for Volcengine. Set ARK_API_KEY or VOLCENGINE_API_KEY environment variable or pass api_key parameter.

What it means

Volcengine (ByteDance Ark) embeddings authenticate with an API key. litellm checks the api_key kwarg, litellm.api_key, then the ARK_API_KEY and VOLCENGINE_API_KEY environment variables; when none is present it raises before sending any request.

Source

Thrown at litellm/main.py:6868

                model=model,
                input=transformed_input,
                custom_llm_provider=custom_llm_provider,
                api_base=api_base,
                api_key=api_key,
                logging_obj=logging,
                timeout=timeout,
                model_response=EmbeddingResponse(),
                optional_params=optional_params,
                litellm_params={},
                client=client,
                aembedding=aembedding,
            )
        elif custom_llm_provider == "volcengine":
            volcengine_key: Final = (
                api_key or litellm.api_key or get_secret_str("ARK_API_KEY") or get_secret_str("VOLCENGINE_API_KEY")
            )
            if volcengine_key is None:
                raise ValueError(
                    "Missing API key for Volcengine. Set ARK_API_KEY or VOLCENGINE_API_KEY environment variable or pass api_key parameter."
                )
            if extra_headers is not None and isinstance(extra_headers, dict):
                headers = extra_headers
            else:
                headers = {}
            response = base_llm_http_handler.embedding(
                model=model,
                input=input,
                timeout=timeout,
                custom_llm_provider=custom_llm_provider,
                logging_obj=logging,
                api_base=api_base,
                optional_params=optional_params,
                litellm_params={},
                model_response=EmbeddingResponse(),
                api_key=volcengine_key,
                client=client,

View on GitHub (pinned to 77b7c6c40c)

Solutions

export ARK_API_KEY=<key> (or VOLCENGINE_API_KEY) in the process environment
Or pass api_key=<key> directly to the embedding call
Or assign litellm.api_key once at startup
Verify the env var is visible: python -c "import os; print(bool(os.environ.get('ARK_API_KEY')))"

Example fix

# before
resp = litellm.embedding(model="volcengine/ep-20240xxx", input=["hi"])

# after
os.environ["ARK_API_KEY"] = "..."
resp = litellm.embedding(model="volcengine/ep-20240xxx", input=["hi"])

Defensive patterns

Strategy: validation

Validate before calling

import os

volc_key = os.environ.get("ARK_API_KEY") or os.environ.get("VOLCENGINE_API_KEY")
if not volc_key:
    raise SystemExit("ARK_API_KEY / VOLCENGINE_API_KEY not set")

Try / catch

try:
    resp = litellm.embedding(model="volcengine/ep-x", input=["hi"])
except ValueError as e:
    if "Volcengine" in str(e):
        raise RuntimeError("Volcengine credentials missing") from e

Prevention

Assert required secret env vars at process start, not at first request
Keep provider credential names in one constants module to avoid typos

When it happens

Trigger: litellm.embedding(model='volcengine/<ep-xxx>', input=[...]) with none of api_key, litellm.api_key, ARK_API_KEY, or VOLCENGINE_API_KEY set.

Common situations: New Volcengine/Ark integration; key stored under a different name (e.g. ARK_TOKEN); secrets not injected into the container or .env not loaded.

Related errors

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