chroma-core/chroma · error · ValueError

The {self.api_key_env_var} environment variable is not set.

Error message

The {self.api_key_env_var} environment variable is not set.

What it means

JinaEmbeddingFunction resolves its API key as api_key or os.getenv(api_key_env_var) — defaulting api_key_env_var to 'JINA_API_KEY' when that env var is already set, otherwise to the constructor argument — and raises this ValueError if nothing resolves. The Jina embeddings API rejects unauthenticated requests, so the EF refuses to initialize without a key. Passing api_key directly is deprecated in favor of the env var.

Source

Thrown at chromadb/utils/embedding_functions/jina_embedding_function.py:91

            raise ValueError(
                "The PIL python package is not installed. Please install it with `pip install pillow`"
            )

        if api_key is not None:
            warnings.warn(
                "Direct api_key configuration will not be persisted. "
                "Please use environment variables via api_key_env_var for persistent storage.",
                DeprecationWarning,
            )

        if os.getenv("JINA_API_KEY") is not None:
            self.api_key_env_var = "JINA_API_KEY"
        else:
            self.api_key_env_var = api_key_env_var

        self.api_key = api_key or os.getenv(self.api_key_env_var)
        if not self.api_key:
            raise ValueError(
                f"The {self.api_key_env_var} environment variable is not set."
            )

        self.model_name = model_name

        # Initialize optional attributes to None
        self.task = task
        self.late_chunking = late_chunking
        self.truncate = truncate
        self.dimensions = dimensions
        self.embedding_type = embedding_type
        self.normalized = normalized
        self.query_config = query_config

        self._api_url = "https://api.jina.ai/v1/embeddings"
        self._session = httpx.Client()
        self._session.headers.update(
            {"Authorization": f"Bearer {self.api_key}", "Accept-Encoding": "identity"}

View on GitHub (pinned to aecdd12c8a)

Solutions

1. export JINA_API_KEY=... (or set it in your process manager/container env) before constructing the EF
2. Call load_dotenv() before creating the embedding function if the key lives in .env
3. Use a custom var name via JinaEmbeddingFunction(model_name=..., api_key_env_var='MY_JINA_KEY') and set that variable
4. Verify in-process: python -c "import os; print(bool(os.getenv('JINA_API_KEY')))"

Example fix

# before
from chromadb.utils.embedding_functions import JinaEmbeddingFunction
ef = JinaEmbeddingFunction(model_name="jina-clip-v1")  # env var not set

# after
import os
from dotenv import load_dotenv
load_dotenv()  # or: os.environ.setdefault("JINA_API_KEY", "jina_...")
assert os.getenv("JINA_API_KEY"), "JINA_API_KEY missing"
ef = JinaEmbeddingFunction(model_name="jina-clip-v1")

import os

if not os.getenv("JINA_API_KEY"):
    raise SystemExit("JINA_API_KEY is required for JinaEmbeddingFunction")

from chromadb.utils.embedding_functions import JinaEmbeddingFunction
ef = JinaEmbeddingFunction(model_name="jina-clip-v1")

try:
    ef = JinaEmbeddingFunction(model_name="jina-clip-v1")
except ValueError as e:
    if "environment variable is not set" in str(e):
        raise RuntimeError("Configure JINA_API_KEY in the deployment environment") from e
    raise

When it happens

Trigger: JinaEmbeddingFunction(model_name='jina-clip-v1') with JINA_API_KEY unset in the shell/process; running under systemd, docker, or a cron job where interactive shell exports (.bashrc) are not applied; setting the var in a different terminal than the one launching the app; typos like JINA_APIKEY.

Common situations: Deploying to containers/PaaS without forwarding secrets; CI pipelines lacking the secret env var; .env files not loaded because python-dotenv load_dotenv() runs after EF construction.

Related errors

• The {api_key_env_var} environment variable is not set.
• The {api_key_env_var} environment variable is not set.
• Missing required arguments: {', '.join([arg.name for arg in
• API key not provided and {self.api_key_env_var} environment
• Jina AI API key is required. Please provide it in the constr

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/b5d958a9359c56e6. Report an issue: GitHub.