{"record":{"id":"2c65e956ac3d2f89","repo":"chroma-core/chroma","slug":"the-self-api-key-env-var-environment-variable-is","errorCode":null,"errorMessage":"The {self.api_key_env_var} environment variable is not set.","messagePattern":"The (.+?) environment variable is not set\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/cloudflare_workers_ai_embedding_function.py","lineNumber":66,"sourceCode":"        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        self.model_name = model_name\n        self.account_id = account_id\n\n        if os.getenv(\"CLOUDFLARE_API_KEY\") is not None:\n            self.api_key_env_var = \"CLOUDFLARE_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        self.gateway_id = gateway_id\n\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        if self.gateway_id:\n            self._api_url = f\"{GATEWAY_BASE_URL}/{self.account_id}/{self.gateway_id}/workers-ai/{self.model_name}\"\n        else:\n            self._api_url = f\"{BASE_URL}/{self.account_id}/ai/run/{self.model_name}\"\n\n        self._session = httpx.Client()\n        self._session.headers.update(\n            {\"Authorization\": f\"Bearer {self.api_key}\", \"Accept-Encoding\": \"identity\"}\n        )\n\n    def __call__(self, input: Documents) -> Embeddings:\n        \"\"\"\n        Generate embeddings for the given documents.\n\n        Args:","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/cloudflare_workers_ai_embedding_function.py#L48-L84","documentation":"The constructor resolves its API key as api_key or os.getenv(api_key_env_var), where api_key_env_var is forced to CLOUDFLARE_API_KEY if that variable is set, otherwise the name you passed (default CHROMA_CLOUDFLARE_API_KEY). With neither a key argument nor a populated variable it refuses to build the client. Passing api_key directly still works but emits a DeprecationWarning because raw keys are not persisted in the function config.","triggerScenarios":"Constructing CloudflareWorkersAIEmbeddingFunction with no api_key= argument while neither CLOUDFLARE_API_KEY nor CHROMA_CLOUDFLARE_API_KEY (or your custom api_key_env_var) is exported in the process environment - fresh shell, CI runner, container, cron job.","commonSituations":"Key lives in .env but load_dotenv() was never called; the variable is exported under a different name than api_key_env_var; the secret was added to a different platform/environment than the one actually running the app.","solutions":["export CLOUDFLARE_API_KEY=<key> - the constructor auto-detects it - or export the exact variable named in the error message.","Call load_dotenv() before constructing the embedding function if the key lives in a .env file.","For quick tests only, pass api_key='...' programmatically; note this raises a DeprecationWarning and will not survive config persistence."],"exampleFix":"# before\n# shell: CLOUDFLARE_API_KEY and CHROMA_CLOUDFLARE_API_KEY unset\nef = CloudflareWorkersAIEmbeddingFunction(model_name='@cf/baai/bge-small-en-v1.5', account_id='abc')  # ValueError\n\n# after\nfrom dotenv import load_dotenv\nload_dotenv()  # .env: CLOUDFLARE_API_KEY=...\nef = CloudflareWorkersAIEmbeddingFunction(model_name='@cf/baai/bge-small-en-v1.5', account_id='abc')","handlingStrategy":"validation","validationCode":"import os\nif not (os.getenv('CLOUDFLARE_API_KEY') or os.getenv('CHROMA_CLOUDFLARE_API_KEY')):\n    raise SystemExit('Cloudflare credential missing: set CLOUDFLARE_API_KEY (auto-detected) before constructing the EF')","typeGuard":null,"tryCatchPattern":"try:\n    ef = CloudflareWorkersAIEmbeddingFunction(model_name=M, account_id=A)\nexcept ValueError as e:\n    if 'environment variable is not set' in str(e):\n        raise SystemExit(f'Missing credential: {e}') from e\n    raise","preventionTips":["Call load_dotenv() at process start, before any embedding function is constructed.","Fail fast on missing secrets in a boot check instead of deep inside library code.","Use CLOUDFLARE_API_KEY so Chroma auto-detects it regardless of the api_key_env_var you pass."],"tags":["chroma","cloudflare","api-key","environment-variable","credentials"],"backgroundTag":"missing-env-var","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}