BerriAI/litellm · error · ValueError

api_key is required. Set via `api_key` parameter or `JINA_AP

Error message

api_key is required. Set via `api_key` parameter or `JINA_API_KEY` environment variable.

What it means

Raised by the Jina rerank config during environment validation: no api_key argument and no JINA_API_KEY environment variable were found, so the Authorization header cannot be built. This fails before any network call.

Source

Thrown at litellm/llms/jina_ai/rerank/transformation.py:144

                # If it's already a dict, keep it as is
                transformed_result["document"] = result["document"]
            transformed_results.append(transformed_result)

        return RerankResponse(
            id=_json_response.get("id") or str(uuid.uuid4()),
            results=transformed_results,
            meta=rerank_meta,
        )  # Return response

    def validate_environment(
        self,
        headers: dict,
        model: str,
        api_key: str | None = None,
        optional_params: dict | None = None,
    ) -> dict:
        if api_key is None:
            raise ValueError("api_key is required. Set via `api_key` parameter or `JINA_API_KEY` environment variable.")
        return {
            "accept": "application/json",
            "content-type": "application/json",
            "authorization": f"Bearer {api_key}",
        }

    def calculate_rerank_cost(
        self,
        model: str,
        custom_llm_provider: str | None = None,
        billed_units: RerankBilledUnits | None = None,
        model_info: ModelInfo | None = None,
    ) -> tuple[float, float]:
        """
        Jina AI reranker is priced at $0.000000018 per token.
        """
        if (
            model_info is None

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Pass api_key directly: litellm.rerank(model='jina_ai/...', query=q, documents=docs, api_key='jina_...').
2. Or export the exact name: export JINA_API_KEY='jina_...' (and pass it via --env or env_file in Docker/CI).
3. For litellm proxy, set api_key on the jina_ai model entry or use the secret manager.

Example fix

# before
litellm.rerank(model='jina_ai/jina-reranker-v2-base-multilingual', query=q, documents=docs)

# after
litellm.rerank(model='jina_ai/jina-reranker-v2-base-multilingual', query=q, documents=docs, api_key=os.environ['JINA_API_KEY'])

def require_jina_key(api_key: str | None = None) -> str:
    key = api_key or os.environ.get('JINA_API_KEY')
    if not key:
        raise RuntimeError('JINA_API_KEY not set; add it to the environment or pass api_key')
    return key

When it happens

Trigger: litellm.rerank(model='jina_ai/jina-reranker-v2-base-multilingual', ...) without api_key while JINA_API_KEY is unset — common in fresh environments, containers, or CI where the env var was not exported.

Common situations: Works locally (env var in shell) but fails in Docker/CI where the variable is not passed; using a proxy config entry that omits api_key; variable named differently (JINA_AI_API_KEY).

Related errors

• {raw_response.text}
• You must be a LiteLLM Enterprise user to use this feature. I
• custom_ui_sso_sign_in_handler is not configured. Please set
• Invalid mode: {custom_auth_settings['mode']}
• api_key (Azure AD token) is required for Azure Foundry Agent

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