{"record":{"id":"7d1a2d0b290a4198","repo":"chroma-core/chroma","slug":"api-key-not-found-in-environment-variable-api-key","errorCode":null,"errorMessage":"API key not found in environment variable {api_key_env_var} or in any existing client instances","messagePattern":"API key not found in environment variable (.+?) or in any existing client instances","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/chroma_cloud_qwen_embedding_function.py","lineNumber":68,"sourceCode":"                Defaults to \"CHROMA_API_KEY\".\n        \"\"\"\n        try:\n            import httpx\n        except ImportError:\n            raise ValueError(\n                \"The httpx python package is not installed. Please install it with `pip install httpx`\"\n            )\n\n        self.api_key_env_var = api_key_env_var\n        # First, try to get API key from environment variable\n        self.api_key = os.getenv(api_key_env_var)\n        # If not found in env var, try to get it from existing client instances\n        if not self.api_key:\n            SharedSystemClient = _get_shared_system_client()\n            self.api_key = SharedSystemClient.get_chroma_cloud_api_key_from_clients()\n        # Raise error if still no API key found\n        if not self.api_key:\n            raise ValueError(\n                f\"API key not found in environment variable {api_key_env_var} \"\n                f\"or in any existing client instances\"\n            )\n\n        self.model = model\n        self.task = task\n        self.instructions = instructions\n\n        self._api_url = get_chroma_embed_url()\n        self._session = httpx.Client()\n        self._session.headers.update(\n            {\n                \"x-chroma-token\": self.api_key,\n                \"x-chroma-embedding-model\": self.model.value,\n            }\n        )\n\n    def _parse_response(self, response: Any) -> Embeddings:","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/chroma_cloud_qwen_embedding_function.py#L50-L86","documentation":"ChromaCloudQwenEmbeddingFunction resolves credentials in two steps: os.getenv(api_key_env_var) (default 'CHROMA_API_KEY'), then a fallback that asks SharedSystemClient.get_chroma_cloud_api_key_from_clients() for the key of any already-authenticated Chroma client in the process. If both come up empty it raises ValueError with the env var name, because every request to the Chroma Embed API needs the x-chroma-token header built from this key.","triggerScenarios":"Constructing the function when CHROMA_API_KEY (or the custom api_key_env_var you passed) is unset/empty AND no PersistentClient/HttpClient with a Chroma Cloud credential exists in-process. Example: passing api_key_env_var=\"QWEN_KEY\" while only CHROMA_API_KEY is exported.","commonSituations":"Local script works (env var in shell) but the same code fails in cron/Docker/CI where the var was never exported; custom api_key_env_var name that does not match the actual environment; API key set only after the EF was constructed; secrets loaded via .env file that was never sourced.","solutions":["export CHROMA_API_KEY=<your key> (or the value of the api_key_env_var you configured) in the environment that runs the process.","If you pass api_key_env_var, make sure it exactly matches the exported variable name (e.g. QWEN_EMBED_KEY).","Alternatively create an authenticated Chroma client first — its API key is picked up from existing client instances.","For .env-based setups, load variables before constructing the embedding function (e.g. dotenv.load_dotenv() at startup)."],"exampleFix":"# before\nef = ChromaCloudQwenEmbeddingFunction(\n    model=ChromaCloudQwenEmbeddingModel.QWEN3_EMBEDDING_0p6B,\n    task=None,\n    api_key_env_var=\"QWEN_KEY\",  # QWEN_KEY not exported -> ValueError\n)\n\n# after\n# export QWEN_KEY=\"ck-...\"\nef = ChromaCloudQwenEmbeddingFunction(\n    model=ChromaCloudQwenEmbeddingModel.QWEN3_EMBEDDING_0p6B,\n    task=None,\n    api_key_env_var=\"QWEN_KEY\",\n)","handlingStrategy":"validation","validationCode":"import os\n\nAPI_KEY_ENV_VAR = \"CHROMA_API_KEY\"  # match the api_key_env_var you will pass\nif not os.getenv(API_KEY_ENV_VAR):\n    raise SystemExit(f\"Export {API_KEY_ENV_VAR} before creating ChromaCloudQwenEmbeddingFunction\")\nef = ChromaCloudQwenEmbeddingFunction(model=ChromaCloudQwenEmbeddingModel.QWEN3_EMBEDDING_0p6B, task=None, api_key_env_var=API_KEY_ENV_VAR)","typeGuard":null,"tryCatchPattern":"try:\n    ef = ChromaCloudQwenEmbeddingFunction(...)\nexcept ValueError as e:\n    if \"API key not found\" in str(e):\n        # prompt for the key / load from secret manager, then construct again\n        raise","preventionTips":["Check os.getenv(api_key_env_var) at application startup, before any client or EF construction.","Keep one constant for the env var name and reuse it for both the export and the constructor argument.","In containers, assert required env vars in the entrypoint so misconfigured deploys fail immediately."],"tags":["api-key","env-var","chroma-cloud","qwen","credentials"],"backgroundTag":"missing-api-key","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}