{"record":{"id":"be41b65157b2bc9b","repo":"chroma-core/chroma","slug":"api-key-not-found-in-environment-variable-self-ap","errorCode":null,"errorMessage":"API key not found in environment variable {self.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_splade_embedding_function.py","lineNumber":49,"sourceCode":"            api_key_env_var (str, optional): Environment variable name that contains your API key.\n                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        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(self.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 {self.api_key_env_var} \"\n                f\"or in any existing client instances\"\n            )\n        self.model = model\n        self.include_tokens = bool(include_tokens)\n        self._api_url = f\"{get_chroma_embed_url()}/embed_sparse\"\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 __del__(self) -> None:\n        \"\"\"\n        Cleanup the HTTP client session when the object is destroyed.\n        \"\"\"","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/chroma_cloud_splade_embedding_function.py#L31-L67","documentation":"The SPLADE constructor resolves its API key by checking os.getenv(self.api_key_env_var) (default 'CHROMA_API_KEY') and then falling back to SharedSystemClient.get_chroma_cloud_api_key_from_clients(); if both are empty it raises ValueError. The key is required to set the x-chroma-token header on every /embed_sparse request.","triggerScenarios":"Creating ChromaCloudSpladeEmbeddingFunction when the named env var is unset/empty and no authenticated Chroma client exists in-process; e.g. passing api_key_env_var=\"SPLADE_KEY\" while the variable was never exported.","commonSituations":"Works locally, fails in Docker/cron/CI where env vars are not propagated; mismatch between the api_key_env_var argument and the actually exported name; key configured only in .env that is loaded after construction; forked worker processes losing the parent's clients.","solutions":["Export the key: export CHROMA_API_KEY=... (or the exact name you passed as api_key_env_var).","Align the api_key_env_var argument with the real variable name in the deployment environment.","Or construct an authenticated Chroma client first — its key is discovered from existing client instances.","Load secrets (dotenv/vault) before instantiating the embedding function."],"exampleFix":"# before\nef = ChromaCloudSpladeEmbeddingFunction(api_key_env_var=\"SPLADE_KEY\")  # ValueError: not found\n\n# after\n# export SPLADE_KEY=\"ck-...\"\nef = ChromaCloudSpladeEmbeddingFunction(api_key_env_var=\"SPLADE_KEY\")","handlingStrategy":"validation","validationCode":"import os\n\nAPI_KEY_ENV_VAR = \"CHROMA_API_KEY\"\nif not os.getenv(API_KEY_ENV_VAR):\n    raise SystemExit(f\"Export {API_KEY_ENV_VAR} before creating ChromaCloudSpladeEmbeddingFunction\")\nef = ChromaCloudSpladeEmbeddingFunction(api_key_env_var=API_KEY_ENV_VAR)","typeGuard":null,"tryCatchPattern":"try:\n    ef = ChromaCloudSpladeEmbeddingFunction(api_key_env_var=\"CHROMA_API_KEY\")\nexcept ValueError as e:\n    if \"API key not found\" in str(e):\n        # fetch from secret manager, os.environ[...] = key, then retry construction\n        raise","preventionTips":["Validate the env var in the container entrypoint or app bootstrap.","Use the same env var name in dev, CI, and prod to avoid drift.","Load .env files at process start, before any embedding function is built."],"tags":["api-key","env-var","chroma-cloud","splade","credentials"],"backgroundTag":"missing-api-key","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}