BerriAI/litellm · error · ValueError

Volcengine API key is required. Set ARK_API_KEY / VOLCENGINE

Error message

Volcengine API key is required. Set ARK_API_KEY / VOLCENGINE_API_KEY or pass api_key.

What it means

The Volcengine Responses API config resolves the key from litellm_params.api_key, then litellm.api_key, then the secrets ARK_API_KEY and VOLCENGINE_API_KEY. If the whole chain is empty, this ValueError is raised while building request headers - the call never reaches the network.

Source

Thrown at litellm/llms/volcengine/responses/transformation.py:115

    def validate_environment(self, headers: dict, model: str, litellm_params: GenericLiteLLMParams | None) -> dict:
        """
        Build auth headers for Volcengine Responses API.
        """
        if litellm_params is None:
            litellm_params = GenericLiteLLMParams()
        elif isinstance(litellm_params, dict):
            litellm_params = GenericLiteLLMParams.model_validate(litellm_params)

        api_key: Final = (
            litellm_params.api_key
            or litellm.api_key
            or get_secret_str("ARK_API_KEY")
            or get_secret_str("VOLCENGINE_API_KEY")
        )

        if api_key is None:
            raise ValueError("Volcengine API key is required. Set ARK_API_KEY / VOLCENGINE_API_KEY or pass api_key.")

        return get_volcengine_headers(api_key=api_key, extra_headers=headers)

    def get_complete_url(
        self,
        api_base: str | None,
        litellm_params: dict,
    ) -> str:
        """
        Construct Volcengine Responses API endpoint.
        """
        base_url = (
            api_base
            or litellm.api_base
            or get_secret_str("VOLCENGINE_API_BASE")
            or get_secret_str("ARK_API_BASE")
            or get_volcengine_base_url()
        )

View on GitHub (pinned to 77b7c6c40c)

Solutions

Pass api_key explicitly to the responses call.
Export ARK_API_KEY (preferred) or VOLCENGINE_API_KEY in the process environment.
In proxy config.yaml, add api_key to the model's litellm_params.
Set it globally: litellm.api_key = ... (checked second in the chain).

Example fix

# before
resp = litellm.responses(model="volcengine/doubao-seed-1-6", input="hello")
# -> ValueError: Volcengine API key is required...

# after
resp = litellm.responses(
    model="volcengine/doubao-seed-1-6",
    input="hello",
    api_key=os.environ["ARK_API_KEY"],
)

Defensive patterns

Strategy: validation

Validate before calling

import os

api_key = kwargs.get("api_key") or litellm.api_key or os.getenv("ARK_API_KEY") or os.getenv("VOLCENGINE_API_KEY")
if not api_key:
    raise RuntimeError("Volcengine Responses API needs api_key or ARK_API_KEY/VOLCENGINE_API_KEY")
resp = litellm.responses(model="volcengine/...", input="hi", api_key=api_key)

Type guard

const hasVolcengineKey = (cfg: {apiKey?: string; arkApiKey?: string; volcengineApiKey?: string}): boolean =>
  Boolean(cfg.apiKey ?? cfg.arkApiKey ?? cfg.volcengineApiKey);

Try / catch

try:
    resp = litellm.responses(model="volcengine/...", input="hi")
except ValueError as e:
    if "Volcengine API key is required" in str(e):
        raise RuntimeError("Missing ARK_API_KEY/VOLCENGINE_API_KEY - check deployment env") from e
    raise

Prevention

Set ARK_API_KEY once at process start rather than relying on per-call arguments.
In the LiteLLM proxy, store api_key in the model entry so routes never depend on shell env.
Add a config sanity check that fails the healthcheck when the key is absent.

When it happens

Trigger: litellm.responses(model="volcengine/...", input="hi") with no api_key argument and neither ARK_API_KEY nor VOLCENGINE_API_KEY in the environment; proxy deployments where the volcengine model entry lacks an api_key in litellm_params.

Common situations: Testing the newer Responses API surface on a machine configured only for the chat completions path; env var present in one shell but the app runs under systemd/PMF with a clean env; key stored under a differently-named var.

Related errors

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