{"record":{"id":"844fa4e3515d7e59","repo":"run-llama/llama_index","slug":"must-pass-in-cohere-api-key-or-specify-via-cohere","errorCode":null,"errorMessage":"Must pass in cohere api key or specify via COHERE_API_KEY environment variable ","messagePattern":"Must pass in cohere api key or specify via COHERE_API_KEY environment variable ","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/evaluation/retrieval/metrics.py","lineNumber":446,"sourceCode":"\n\nclass CohereRerankRelevancyMetric(BaseRetrievalMetric):\n    \"\"\"Cohere rerank relevancy metric.\"\"\"\n\n    metric_name: ClassVar[str] = \"cohere_rerank_relevancy\"\n    model: str = Field(description=\"Cohere model name.\")\n\n    _client: Any = PrivateAttr()\n\n    def __init__(\n        self,\n        model: str = \"rerank-english-v2.0\",\n        api_key: Optional[str] = None,\n    ):\n        try:\n            api_key = api_key or os.environ[\"COHERE_API_KEY\"]\n        except IndexError:\n            raise ValueError(\n                \"Must pass in cohere api key or \"\n                \"specify via COHERE_API_KEY environment variable \"\n            )\n        try:\n            from cohere import Client  # pants: no-infer-dep\n        except ImportError:\n            raise ImportError(\n                \"Cannot import cohere package, please `pip install cohere`.\"\n            )\n\n        super().__init__(model=model)\n        self._client = Client(api_key=api_key)\n\n    def _get_agg_func(self, agg: Literal[\"max\", \"median\", \"mean\"]) -> Callable:\n        \"\"\"Get agg func.\"\"\"\n        return _AGG_FUNC[agg]\n\n    def compute(","sourceCodeStart":428,"sourceCodeEnd":464,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/evaluation/retrieval/metrics.py#L428-L464","documentation":"Raised by CohereRerankRelevancyMetric.__init__ when no Cohere API key is supplied: the constructor falls back to the COHERE_API_KEY environment variable, and when neither is present it tries to raise this ValueError. Note a latent bug: the code catches IndexError, but os.environ[...] raises KeyError when the variable is missing, so in practice you will usually see KeyError('COHERE_API_KEY') instead of this ValueError.","triggerScenarios":"Instantiating CohereRerankRelevancyMetric(model=..., api_key=None) (or omitting api_key) in a process where the COHERE_API_KEY environment variable is not set — e.g. building a RetrieverEvaluator with metrics=['cohere_rerank_relevancy'] via resolve_metrics without configuring Cohere credentials.","commonSituations":"CI runs or containers where secrets are not exported; local shells where the key was set in a different terminal; .env files loaded after module import; the IndexError/KeyError mismatch surfacing after a Python or llama-index upgrade makes the intended ValueError unreachable.","solutions":["Pass the key explicitly: CohereRerankRelevancyMetric(api_key=os.environ['COHERE_API_KEY']) after exporting it in the shell (export COHERE_API_KEY=...).","Set the variable in the environment that launches the process (docker-compose env, CI secret, systemd Environment=) rather than relying on the constructor.","If you see KeyError instead of this ValueError, that is the upstream catch-the-wrong-exception bug (IndexError vs KeyError) — catch KeyError too or supply api_key explicitly to bypass it."],"exampleFix":"// before\nmetric = CohereRerankRelevancyMetric()  # COHERE_API_KEY unset\n\n# after\nexport COHERE_API_KEY=...   # or:\nmetric = CohereRerankRelevancyMetric(api_key=get_cohere_key())","handlingStrategy":"validation","validationCode":"import os\n\ncohere_key = os.environ.get(\"COHERE_API_KEY\")\nif not cohere_key and not explicit_api_key:\n    raise RuntimeError(\"Configure COHERE_API_KEY before building CohereRerankRelevancyMetric\")","typeGuard":null,"tryCatchPattern":"try:\n    metric = CohereRerankRelevancyMetric(api_key=cohere_key)\nexcept ValueError as e:\n    if \"cohere api key\" in str(e).lower():\n        # handle missing credentials\n    else:\n        raise\n# NOTE: due to the IndexError/KeyError bug, also catch KeyError('COHERE_API_KEY')","preventionTips":["Export COHERE_API_KEY in the launching environment (compose env, CI secret, shell profile) rather than relying on the constructor fallback.","Assert required env vars at process startup with a fast-fail checklist.","Pass api_key explicitly from your own secret manager so library fallback paths are never exercised."],"tags":["authentication","environment-variables","cohere","configuration"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}