{"record":{"id":"898ccf61770f213f","repo":"chroma-core/chroma","slug":"the-api-key-env-var-environment-variable-is-not-898ccf","errorCode":null,"errorMessage":"The {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/nomic_embedding_function.py","lineNumber":53,"sourceCode":"            query_config (Optional[NomicQueryConfig]): The configuration for setting task type for queries\n            api_key_env_var (str): The environment variable name for the Nomic API key. Defaults to \"NOMIC_API_KEY\".\n\n            Supported task types: search_document, search_query, classification, clustering\n        \"\"\"\n        try:\n            from nomic import embed\n        except ImportError:\n            raise ValueError(\n                \"The nomic python package is not installed. Please install it with `pip install nomic`\"\n            )\n\n        self.model = model\n        self.task_type = task_type\n        self.api_key_env_var = api_key_env_var\n        self.api_key = os.getenv(api_key_env_var)\n        self.query_config = query_config\n        if not self.api_key:\n            raise ValueError(f\"The {api_key_env_var} environment variable is not set.\")\n        self.embed = embed\n\n    def __call__(self, input: Documents) -> Embeddings:\n        if not all(isinstance(item, str) for item in input):\n            raise ValueError(\"Nomic only supports text documents, not images\")\n        output = self.embed.text(\n            model=self.model,\n            texts=input,\n            task_type=self.task_type,\n        )\n        return [np.array(data.embedding) for data in output.data]\n\n    def embed_query(self, input: Documents) -> Embeddings:\n        if not all(isinstance(item, str) for item in input):\n            raise ValueError(\"Nomic only supports text queries, not images\")\n\n        task_type = (\n            self.query_config.get(\"task_type\") if self.query_config else self.task_type","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/nomic_embedding_function.py#L35-L71","documentation":"NomicEmbeddingFunction.__init__ reads the API key with os.getenv(api_key_env_var) (default variable name \"NOMIC_API_KEY\") and raises ValueError when the value is falsy. This fires at construction time, before any embedding call, because the Nomic client needs the key to authenticate against the Nomic Atlas API. Note that an empty string counts as unset, since the check is `if not self.api_key`.","triggerScenarios":"Instantiating NomicEmbeddingFunction(model=..., task_type=..., query_config=...) in a shell/process where NOMIC_API_KEY is not exported; passing a custom api_key_env_var (e.g. \"MY_NOMIC_KEY\") that does not exist; setting the variable to an empty string (export NOMIC_API_KEY=\"\"); running under systemd/docker/cron where the env var was only set in an interactive shell.","commonSituations":"CI pipelines and Docker containers that strip environment variables; deploying to production where the key is stored in a secrets manager but never exported; typos in the custom env var name; scripts that read the key from .env but forget to load python-dotenv before constructing the EF.","solutions":["Export the variable before starting Python: export NOMIC_API_KEY=\"nk-...\" (get a key from the Nomic Atlas dashboard)","If you use a different variable name, pass it explicitly and verify it exists: NomicEmbeddingFunction(..., api_key_env_var=\"MY_NOMIC_KEY\") after export MY_NOMIC_KEY=...","In docker-compose/Kubernetes, add the variable to the environment/env section of the service spec","For .env files, load them before construction: from dotenv import load_dotenv; load_dotenv()"],"exampleFix":"// before (KeyError-free but crashes at runtime)\nfn = NomicEmbeddingFunction(model=\"nomic-embed-text-v1.5\", task_type=\"search_query\", query_config={\"task_type\": \"search_query\"})  # NOMIC_API_KEY not set -> ValueError\n\n// after\nimport os\nfrom dotenv import load_dotenv\nload_dotenv()  # loads NOMIC_API_KEY from .env\nif not os.getenv(\"NOMIC_API_KEY\"):\n    raise SystemExit(\"Set NOMIC_API_KEY before running\")\nfn = NomicEmbeddingFunction(model=\"nomic-embed-text-v1.5\", task_type=\"search_query\", query_config={\"task_type\": \"search_query\"})","handlingStrategy":"validation","validationCode":"import os\nname = \"NOMIC_API_KEY\"  # or your custom api_key_env_var\nif not os.getenv(name):\n    raise SystemExit(f\"Missing required env var {name}; export it before starting.\")\nfn = NomicEmbeddingFunction(model=\"nomic-embed-text-v1.5\", task_type=\"search_document\", query_config={\"task_type\": \"search_query\"}, api_key_env_var=name)","typeGuard":null,"tryCatchPattern":"try:\n    fn = NomicEmbeddingFunction(model=..., task_type=..., query_config=...)\nexcept ValueError as e:\n    if \"environment variable is not set\" in str(e):\n        raise SystemExit(\"Nomic API key missing — set NOMIC_API_KEY and restart\") from e\n    raise","preventionTips":["Set required env vars in docker-compose/Kubernetes env blocks, not interactively","Fail fast at app startup with an env-var checklist instead of deep inside EF construction","If loading from .env, call load_dotenv() before any embedding-function construction","Never set the variable to an empty string — the check treats empty as unset"],"tags":["nomic","embedding-function","environment-variable","api-key","chroma"],"backgroundTag":"missing-env-var","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}