FoundationAgents/MetaGPT · error · ImportError

`llama-index-postprocessor-cohere-rerank` package not found,

Error message

`llama-index-postprocessor-cohere-rerank` package not found, please run `pip install llama-index-postprocessor-cohere-rerank`

What it means

RankerFactory._create_cohere_rerank raises this ImportError when llama-index-postprocessor-cohere-rerank is missing. CohereRerank is imported lazily inside the factory method, so the error surfaces only at ranker construction time, not at metagpt import time.

Source

Thrown at metagpt/rag/factories/ranker.py:57

    def _create_llm_ranker(self, config: LLMRankerConfig, **kwargs) -> LLMRerank:
        config.llm = self._extract_llm(config, **kwargs)

        return LLMRerank(**config.model_dump())

    def _create_colbert_ranker(self, config: ColbertRerankConfig, **kwargs) -> LLMRerank:
        try:
            from llama_index.postprocessor.colbert_rerank import ColbertRerank
        except ImportError:
            raise ImportError(
                "`llama-index-postprocessor-colbert-rerank` package not found, please run `pip install llama-index-postprocessor-colbert-rerank`"
            )
        return ColbertRerank(**config.model_dump())

    def _create_cohere_rerank(self, config: CohereRerankConfig, **kwargs) -> LLMRerank:
        try:
            from llama_index.postprocessor.cohere_rerank import CohereRerank
        except ImportError:
            raise ImportError(
                "`llama-index-postprocessor-cohere-rerank` package not found, please run `pip install llama-index-postprocessor-cohere-rerank`"
            )
        return CohereRerank(**config.model_dump())

    def _create_bge_rerank(self, config: BGERerankConfig, **kwargs) -> LLMRerank:
        try:
            from llama_index.postprocessor.flag_embedding_reranker import (
                FlagEmbeddingReranker,
            )
        except ImportError:
            raise ImportError(
                "`llama-index-postprocessor-flag-embedding-reranker` package not found, please run `pip install llama-index-postprocessor-flag-embedding-reranker`"
            )
        return FlagEmbeddingReranker(**config.model_dump())

    def _create_object_ranker(self, config: ObjectRankerConfig, **kwargs) -> LLMRerank:
        return ObjectSortPostprocessor(**config.model_dump())

View on GitHub (pinned to 11cdf466d0)

Solutions

pip install llama-index-postprocessor-cohere-rerank
Set the COHERE_API_KEY env var afterwards, since CohereRerank also needs an API key at runtime
Or pin the package in your dependency manifest to keep CI and prod in sync

Example fix

// before
rankers = get_rankers(configs=[CohereRerankConfig(top_n=2)])  # ImportError

// after
// pip install llama-index-postprocessor-cohere-rerank
rankers = get_rankers(configs=[CohereRerankConfig(top_n=2, api_key=os.environ["COHERE_API_KEY"])])

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("llama_index.postprocessor.cohere_rerank") is None:
    raise SystemExit("Install first: pip install llama-index-postprocessor-cohere-rerank")

Try / catch

try:
    ranker = get_rankers(configs=[cohere_cfg])
except ImportError as e:
    if "cohere-rerank" in str(e):
        logger.warning("cohere rerank unavailable, falling back to no reranker")
        ranker = None
    else:
        raise

Prevention

Install llama-index-postprocessor-cohere-rerank wherever cohere reranking is configured
Set COHERE_API_KEY via environment, never hardcode it in ranker configs
Smoke-test ranker construction in CI to catch missing extras before deploy

When it happens

Trigger: Building rankers with a CohereRerankConfig (e.g. via get_rankers or retriever config listing a cohere reranker) without the cohere rerank package installed.

Common situations: Switching a RAG pipeline to Cohere reranking without adding the extra dependency; environments where only metagpt[rag] core extras were installed; llama-index >= 0.10 where each postprocessor is its own distribution.

Related errors

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/4f937f356f06dd8f. Report an issue: GitHub.