{"record":{"id":"a89d1a8d458e7831","repo":"chroma-core/chroma","slug":"the-self-api-key-env-var-environment-variable-mu","errorCode":null,"errorMessage":"The {self.api_key_env_var} environment variable must be set if vertexai is not enabled.","messagePattern":"The (.+?) environment variable must be set if vertexai is not enabled\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/google_embedding_function.py","lineNumber":63,"sourceCode":"        except ImportError:\n            raise ValueError(\n                \"The google-genai python package is not installed. Please install it with `pip install google-genai`\"\n            )\n\n        self.model_name = model_name\n        self.task_type = task_type\n        self.dimension = dimension\n        self.api_key_env_var = api_key_env_var\n        self.vertexai = vertexai\n        self.project = project\n        self.location = location\n        self.api_key = os.getenv(self.api_key_env_var) if self.api_key_env_var else None\n        if self.api_key and self.vertexai:\n            raise ValueError(\n                \"Vertex AI and API key are mutually exclusive in the client initializer.\"\n            )\n        if not self.api_key and not self.vertexai:\n            raise ValueError(\n                f\"The {self.api_key_env_var} environment variable must be set if vertexai is not enabled.\"\n            )\n\n        from google.genai import types\n\n        self.client = genai.Client(\n            api_key=self.api_key,\n            vertexai=vertexai,\n            project=project,\n            location=location,\n            http_options=types.HttpOptions(\n                headers={\"x-goog-api-client\": f\"chroma/{__version__}\"}\n            ),\n        )\n\n    def __call__(self, input: Documents) -> Embeddings:\n        \"\"\"\n        Generate embeddings for the given documents.","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/google_embedding_function.py#L45-L81","documentation":"Raised in GoogleGeminiEmbeddingFunction.__init__ when no API key is found AND vertexai is falsy. The class reads the key with os.getenv(api_key_env_var) (default 'GEMINI_API_KEY') at construction time; if the variable is unset and Vertex mode is not enabled there is no credential for genai.Client, so initialization stops. The actual message interpolates the env var name that was checked.","triggerScenarios":"Constructing GoogleGeminiEmbeddingFunction() with GEMINI_API_KEY absent; passing api_key_env_var='GOOGLE_API_KEY' when only GEMINI_API_KEY is exported (or vice versa); the variable existing in your shell but not in the Python process (systemd unit, docker exec, cron, IDE run configuration); a .env file that was never loaded; passing vertexai=False/None while intending to use Application Default Credentials.","commonSituations":"Works locally, fails when deployed because the secret was not propagated to docker-compose/Kubernetes/cron; key stored in .env but python-dotenv's load_dotenv() never called; renamed env var between environments; relying on GCP ADC without flipping vertexai=True.","solutions":["Export the variable in the process that runs Chroma: export GEMINI_API_KEY=...","Make api_key_env_var match the variable you actually set (e.g. pass api_key_env_var='GOOGLE_API_KEY' if that is what your secret store injects)","Call load_dotenv() before constructing the embedding function if the key lives in .env","If you are on GCP with service-account/ADC auth, construct with vertexai=True plus project and location instead of a key"],"exampleFix":"# before\nimport os\n# GEMINI_API_KEY not set in this process\nfrom chromadb.utils.embedding_functions import GoogleGeminiEmbeddingFunction\nef = GoogleGeminiEmbeddingFunction()  # ValueError: The GEMINI_API_KEY environment variable must be set...\n\n# after\nfrom dotenv import load_dotenv\nload_dotenv()  # .env contains GEMINI_API_KEY=...\nfrom chromadb.utils.embedding_functions import GoogleGeminiEmbeddingFunction\nef = GoogleGeminiEmbeddingFunction()","handlingStrategy":"validation","validationCode":"import os\n\nAPI_KEY_ENV = \"GEMINI_API_KEY\"\n\nif not os.getenv(API_KEY_ENV):\n    raise SystemExit(\n        f\"Set {API_KEY_ENV} (or pass api_key_env_var / vertexai=True for ADC) before starting\"\n    )\n\nfrom chromadb.utils.embedding_functions import GoogleGeminiEmbeddingFunction\nef = GoogleGeminiEmbeddingFunction(api_key_env_var=API_KEY_ENV)","typeGuard":null,"tryCatchPattern":"try:\n    ef = GoogleGeminiEmbeddingFunction()\nexcept ValueError as e:\n    if \"environment variable\" in str(e):\n        # config error, not transient - surface to operator\n        raise SystemExit(f\"Embedding auth not configured: {e}\") from e\n    raise","preventionTips":["Fail fast at process start: assert the env var exists before any embedding work","Load .env with python-dotenv at entrypoint, not after client construction","In containers, declare the env var explicitly (ENV/compose 'environment') so a missing secret is visible in config, not at runtime"],"tags":["gemini","api-key","environment-variable","google-genai","chroma"],"backgroundTag":"missing-api-key-env-var","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}