What causes "GradientAI API key not found" in BerriAI/litellm?

Set the environment variable: export GRADIENT_AI_API_KEY= (or add it to your .env / secret manager).

BerriAI/litellm · error · ValueError

GradientAI API key not found

Error message

GradientAI API key not found

What it means

Thrown by GradientAIChatConfig.validate_environment when no API key can be resolved. LiteLLM first uses the api_key argument passed to the completion call, then falls back to the GRADIENT_AI_API_KEY environment variable (via get_secret_str); if both are absent it raises this ValueError before any HTTP request is made. It is a configuration error, not a network or provider error.

Source

Thrown at litellm/llms/gradient_ai/chat/transformation.py:90

            "include_guardrails_info",
            "provide_citations",
            "retrieval_method",
        ]
        return supported_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,
    ):
        api_key = api_key or get_secret_str("GRADIENT_AI_API_KEY")
        if api_key is None:
            raise ValueError("GradientAI API key not found")
        if headers is None:
            headers = {}
        headers["Authorization"] = f"Bearer {api_key}"
        headers["Content-Type"] = "application/json"
        return 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:
        gradient_ai_endpoint: Final = get_secret_str("GRADIENT_AI_AGENT_ENDPOINT")
        complete_url = f"{GRADIENT_AI_SERVERLESS_ENDPOINT}/v1/chat/completions"

View on GitHub (pinned to 6c2dcb801b)

Solutions

Set the environment variable: export GRADIENT_AI_API_KEY=<your key> (or add it to your .env / secret manager).
Or pass the key explicitly per call: litellm.completion(model='gradient_ai/...', api_key='...', messages=[...]).
If using a proxy (LiteLLM proxy), add the gradient_ai key to the virtual key's model settings / environment config.
Verify with a quick check that the variable is visible to the process (e.g. `env | grep GRADIENT`) — empty strings do not count as set.

Example fix

# before
response = litellm.completion(model='gradient_ai/llama-3.1-8b-instruct', messages=[{'role':'user','content':'hi'}])
# raises ValueError: GradientAI API key not found

# after
response = litellm.completion(
    model='gradient_ai/llama-3.1-8b-instruct',
    messages=[{'role':'user','content':'hi'}],
    api_key=os.environ['GRADIENT_AI_API_KEY'],
)

Defensive patterns

Strategy: validation

Validate before calling

import os

def has_gradient_ai_key(api_key: str | None = None) -> bool:
    return bool(api_key or os.environ.get("GRADIENT_AI_API_KEY"))

if not has_gradient_ai_key():
    raise RuntimeError("GRADIENT_AI_API_KEY is not set; refusing to call gradient_ai")

Try / catch

try:
    litellm.completion(model="gradient_ai/...", messages=msgs, api_key=key)
except ValueError as e:
    if "API key not found" in str(e):
        # config problem, not transient — fail loudly / alert
        raise

Prevention

Set GRADIENT_AI_API_KEY in your secret manager and assert it is non-empty at app startup before any gradient_ai call.
Pass api_key explicitly from your secret store instead of relying on ambient env when running in shared environments.

When it happens

Trigger: Calling litellm.completion(..., model='gradient_ai/<model>') with neither api_key= supplied nor the GRADIENT_AI_API_KEY env var set (also fails if the secret is set to an empty string, since get_secret_str returns None for empty values).

Common situations: Local dev machine where .env was not loaded; CI/production where the secret was not injected; typo in the env var name (e.g. GRADIENTAI_API_KEY); using a custom key manager but forgetting to pass it per-request.

Related errors

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