{"record":{"id":"8f01b71e7f0fce65","repo":"FoundationAgents/MetaGPT","slug":"llama-index-postprocessor-colbert-rerank-package","errorCode":null,"errorMessage":"`llama-index-postprocessor-colbert-rerank` package not found, please run `pip install llama-index-postprocessor-colbert-rerank`","messagePattern":"`llama-index-postprocessor-colbert-rerank` package not found, please run `pip install llama-index-postprocessor-colbert-rerank`","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"metagpt/rag/factories/ranker.py","lineNumber":48,"sourceCode":"        super().__init__(creators)\n\n    def get_rankers(self, configs: list[BaseRankerConfig] = None, **kwargs) -> list[BaseNodePostprocessor]:\n        \"\"\"Creates and returns a retriever instance based on the provided configurations.\"\"\"\n        if not configs:\n            return []\n\n        return super().get_instances(configs, **kwargs)\n\n    def _create_llm_ranker(self, config: LLMRankerConfig, **kwargs) -> LLMRerank:\n        config.llm = self._extract_llm(config, **kwargs)\n\n        return LLMRerank(**config.model_dump())\n\n    def _create_colbert_ranker(self, config: ColbertRerankConfig, **kwargs) -> LLMRerank:\n        try:\n            from llama_index.postprocessor.colbert_rerank import ColbertRerank\n        except ImportError:\n            raise ImportError(\n                \"`llama-index-postprocessor-colbert-rerank` package not found, please run `pip install llama-index-postprocessor-colbert-rerank`\"\n            )\n        return ColbertRerank(**config.model_dump())\n\n    def _create_cohere_rerank(self, config: CohereRerankConfig, **kwargs) -> LLMRerank:\n        try:\n            from llama_index.postprocessor.cohere_rerank import CohereRerank\n        except ImportError:\n            raise ImportError(\n                \"`llama-index-postprocessor-cohere-rerank` package not found, please run `pip install llama-index-postprocessor-cohere-rerank`\"\n            )\n        return CohereRerank(**config.model_dump())\n\n    def _create_bge_rerank(self, config: BGERerankConfig, **kwargs) -> LLMRerank:\n        try:\n            from llama_index.postprocessor.flag_embedding_reranker import (\n                FlagEmbeddingReranker,\n            )","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/FoundationAgents/MetaGPT/blob/11cdf466d042aece04fc6cfd13b28e1a70341b1f/metagpt/rag/factories/ranker.py#L30-L66","documentation":"RankerFactory._create_colbert_ranker raises this ImportError when the optional dependency llama-index-postprocessor-colbert-rerank is not installed. MetaGPT lazily imports ColbertRerank only when a ColbertRerankConfig is requested, so the base metagpt install does not pull the package in.","triggerScenarios":"Calling get_rankers (or building a RAG retriever pipeline) with a ColbertRerankConfig while llama-index-postprocessor-colbert-rerank is absent from the environment.","commonSituations":"Enabling colbert reranking in rag config.yaml (rankers entry with type colbert) on a fresh install; upgrading llama-index which split postprocessors into separate distributions; CI environments that only install metagpt core requirements.","solutions":["pip install llama-index-postprocessor-colbert-rerank","Or add it to your project's dependency list / requirements.txt so CI installs it","Or switch the ranker config to one whose dependency you already have (e.g. object ranker needs no extra package)"],"exampleFix":"// before\nrankers = get_rankers(configs=[ColbertRerankConfig()])  # ImportError\n\n// after\n// pip install llama-index-postprocessor-colbert-rerank\nrankers = get_rankers(configs=[ColbertRerankConfig(model_name=\"colbert-irip\"...)])","handlingStrategy":"validation","validationCode":"import importlib.util\nif importlib.util.find_spec(\"llama_index.postprocessor.colbert_rerank\") is None:\n    raise SystemExit(\"Install first: pip install llama-index-postprocessor-colbert-rerank\")","typeGuard":null,"tryCatchPattern":"try:\n    rankers = get_rankers(configs=[colbert_cfg])\nexcept ImportError as e:\n    if \"colbert-rerank\" in str(e):\n        subprocess.run([sys.executable, \"-m\", \"pip\", \"install\", \"llama-index-postprocessor-colbert-rerank\"], check=True)\n        rankers = get_rankers(configs=[colbert_cfg])\n    else:\n        raise","preventionTips":["Declare every llama-index postprocessor extra your ranker config references in requirements.txt","Add a startup dependency check (importlib.util.find_spec) before building the RAG pipeline","Pin llama-index package versions so optional extras resolve consistently"],"tags":["rag","reranker","dependency","importerror"],"backgroundTag":null,"analyzedSha":"11cdf466d042aece04fc6cfd13b28e1a70341b1f","analyzedAt":"2026-08-14T23:20:02.994Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}