FoundationAgents/MetaGPT · error · ImportError

`llama-index-postprocessor-colbert-rerank` package not found

Error message

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

What it means

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.

Source

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

        super().__init__(creators)

    def get_rankers(self, configs: list[BaseRankerConfig] = None, **kwargs) -> list[BaseNodePostprocessor]:
        """Creates and returns a retriever instance based on the provided configurations."""
        if not configs:
            return []

        return super().get_instances(configs, **kwargs)

    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,
            )

View on GitHub (pinned to 11cdf466d0)

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)

Example fix

// before
rankers = get_rankers(configs=[ColbertRerankConfig()])  # ImportError

// after
// pip install llama-index-postprocessor-colbert-rerank
rankers = get_rankers(configs=[ColbertRerankConfig(model_name="colbert-irip"...)])

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try:
    rankers = get_rankers(configs=[colbert_cfg])
except ImportError as e:
    if "colbert-rerank" in str(e):
        subprocess.run([sys.executable, "-m", "pip", "install", "llama-index-postprocessor-colbert-rerank"], check=True)
        rankers = get_rankers(configs=[colbert_cfg])
    else:
        raise

Prevention

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

When it happens

Trigger: Calling get_rankers (or building a RAG retriever pipeline) with a ColbertRerankConfig while llama-index-postprocessor-colbert-rerank is absent from the environment.

Common situations: 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.

Related errors

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