BerriAI/litellm · error · ValueError

api_key is required for Volcengine authentication

Error message

api_key is required for Volcengine authentication

What it means

VolcEngineEmbeddingConfig.validate_environment builds the Authorization headers for the Ark embedding call via get_volcengine_headers(api_key). If the api_key argument is None at that point (no key resolved from call kwargs, litellm_params, or the ARK_API_KEY/VOLCENGINE_API_KEY environment chain), it raises this ValueError before any request is sent.

Source

Thrown at litellm/llms/volcengine/embedding/transformation.py:196

            transformed_response["id"] = response_json["id"]

        # Create EmbeddingResponse from transformed data
        return EmbeddingResponse(**transformed_response)

    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 return headers"""
        # Get Volcengine headers
        if api_key is None:
            raise ValueError("api_key is required for Volcengine authentication")
        volcengine_headers: Final = get_volcengine_headers(api_key)
        return {**headers, **volcengine_headers}

    def get_error_class(self, error_message: str, status_code: int, headers: dict | httpx.Headers) -> BaseLLMException:
        """Get error class for Volcengine errors"""
        from ..common_utils import VolcEngineError

        # Convert dict to httpx.Headers if needed
        if isinstance(headers, dict):
            headers = httpx.Headers(headers)
        return VolcEngineError(
            status_code=status_code,
            message=error_message,
            headers=headers,
        )

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Set the environment variable: export ARK_API_KEY=... (or VOLCENGINE_API_KEY).
2. Or pass it explicitly: litellm.embedding(model="volcengine/...", input=[...], api_key=...).
3. If using a .env file, load it before importing/invoking litellm (from dotenv import load_dotenv; load_dotenv()).
4. In the LiteLLM proxy, define api_key in the model_list entry's litellm_params for the volcengine model.

Example fix

# before
resp = litellm.embedding(model="volcengine/ep-20240903144444", input=["hi"])
# -> ValueError: api_key is required for Volcengine authentication

# after
import os
os.environ["ARK_API_KEY"] = "<your-ark-key>"
# or inline:
resp = litellm.embedding(
    model="volcengine/ep-20240903144444",
    input=["hi"],
    api_key="<your-ark-key>",
)

import os

VOLC_KEY = os.getenv("ARK_API_KEY") or os.getenv("VOLCENGINE_API_KEY")
if not VOLC_KEY:
    raise RuntimeError("Set ARK_API_KEY (or VOLCENGINE_API_KEY) before embedding")
resp = litellm.embedding(model="volcengine/ep-...", input=inputs, api_key=VOLC_KEY)

const hasVolcengineKey = (env: Record<string, string | undefined>): boolean =>
  Boolean(env.ARK_API_KEY ?? env.VOLCENGINE_API_KEY);

try:
    resp = litellm.embedding(model="volcengine/ep-...", input=inputs)
except ValueError as e:
    if "api_key is required for Volcengine" in str(e):
        raise RuntimeError("Configure ARK_API_KEY in the deployment environment") from e
    raise

When it happens

Trigger: litellm.embedding(model="volcengine/...", input=[...]) in a shell/container where neither api_key nor ARK_API_KEY/VOLCENGINE_API_KEY is set; a typo'd env var name (e.g. VOLC_ENGINE_API_KEY); the key set in a .env file that the process never loaded.

Common situations: Local runs where the key lives only in the deploy environment; Docker/CI containers missing the env var; rotating keys and leaving the old var deleted; multi-provider code that sets keys per provider and misses Volcengine.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Volcengine API key is required. Set ARK_API_KEY / VOLCENGINE
• Voyage API key is required for multimodal embeddings. Set VO
• Voyage AI API key is required. Set via `api_key` parameter o
• API key is required
• Missing API key for Volcengine. Set ARK_API_KEY or VOLCENGIN

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