{"record":{"id":"b5d958a9359c56e6","repo":"chroma-core/chroma","slug":"the-self-api-key-env-var-environment-variable-is-b5d958","errorCode":null,"errorMessage":"The {self.api_key_env_var} environment variable is not set.","messagePattern":"The (.+?) environment variable is not set\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/jina_embedding_function.py","lineNumber":91,"sourceCode":"            raise ValueError(\n                \"The PIL python package is not installed. Please install it with `pip install pillow`\"\n            )\n\n        if api_key is not None:\n            warnings.warn(\n                \"Direct api_key configuration will not be persisted. \"\n                \"Please use environment variables via api_key_env_var for persistent storage.\",\n                DeprecationWarning,\n            )\n\n        if os.getenv(\"JINA_API_KEY\") is not None:\n            self.api_key_env_var = \"JINA_API_KEY\"\n        else:\n            self.api_key_env_var = api_key_env_var\n\n        self.api_key = api_key or os.getenv(self.api_key_env_var)\n        if not self.api_key:\n            raise ValueError(\n                f\"The {self.api_key_env_var} environment variable is not set.\"\n            )\n\n        self.model_name = model_name\n\n        # Initialize optional attributes to None\n        self.task = task\n        self.late_chunking = late_chunking\n        self.truncate = truncate\n        self.dimensions = dimensions\n        self.embedding_type = embedding_type\n        self.normalized = normalized\n        self.query_config = query_config\n\n        self._api_url = \"https://api.jina.ai/v1/embeddings\"\n        self._session = httpx.Client()\n        self._session.headers.update(\n            {\"Authorization\": f\"Bearer {self.api_key}\", \"Accept-Encoding\": \"identity\"}","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/jina_embedding_function.py#L73-L109","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["export JINA_API_KEY=... (or set it in your process manager/container env) before constructing the EF","Call load_dotenv() before creating the embedding function if the key lives in .env","Use a custom var name via JinaEmbeddingFunction(model_name=..., api_key_env_var='MY_JINA_KEY') and set that variable","Verify in-process: python -c \"import os; print(bool(os.getenv('JINA_API_KEY')))\""],"exampleFix":"# before\nfrom chromadb.utils.embedding_functions import JinaEmbeddingFunction\nef = JinaEmbeddingFunction(model_name=\"jina-clip-v1\")  # env var not set\n\n# after\nimport os\nfrom dotenv import load_dotenv\nload_dotenv()  # or: os.environ.setdefault(\"JINA_API_KEY\", \"jina_...\")\nassert os.getenv(\"JINA_API_KEY\"), \"JINA_API_KEY missing\"\nef = JinaEmbeddingFunction(model_name=\"jina-clip-v1\")","handlingStrategy":"validation","validationCode":"import os\n\nif not os.getenv(\"JINA_API_KEY\"):\n    raise SystemExit(\"JINA_API_KEY is required for JinaEmbeddingFunction\")\n\nfrom chromadb.utils.embedding_functions import JinaEmbeddingFunction\nef = JinaEmbeddingFunction(model_name=\"jina-clip-v1\")","typeGuard":null,"tryCatchPattern":"try:\n    ef = JinaEmbeddingFunction(model_name=\"jina-clip-v1\")\nexcept ValueError as e:\n    if \"environment variable is not set\" in str(e):\n        raise RuntimeError(\"Configure JINA_API_KEY in the deployment environment\") from e\n    raise","preventionTips":["Load .env (load_dotenv()) before any EF construction","Declare secrets in the orchestrator (docker-compose env, k8s secret, CI masked var) rather than relying on shell exports","Use the deprecated api_key= parameter only for throwaway experiments, never in persisted configs"],"tags":["python","authentication","environment-variables","jina","api-key"],"backgroundTag":"missing-env-var","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}