FoundationAgents/MetaGPT · error · ImportError

To use the experience pool, you need to install the rag modu

Error message

To use the experience pool, you need to install the rag module.

What it means

ExpPoolManager's BM25 backend builder imports metagpt.rag.engines.SimpleEngine and BM25 schema classes; if the optional rag dependencies are absent the ImportError is re-raised as 'To use the experience pool, you need to install the rag module.'. BM25 is the default retrieval mode, so enabling the experience pool without the rag extra hits this immediately.

Source

Thrown at metagpt/exp_pool/manager.py:163

    def _create_bm25_storage(self) -> "SimpleEngine":
        """Creates or loads BM25 storage.

        This function attempts to create a new BM25 storage if the specified
        document store path does not exist. If the path exists, it loads the
        existing BM25 storage.

        Returns:
            SimpleEngine: An instance of SimpleEngine configured with BM25 storage.

        Raises:
            ImportError: If required modules are not installed.
        """

        try:
            from metagpt.rag.engines import SimpleEngine
            from metagpt.rag.schema import BM25IndexConfig, BM25RetrieverConfig
        except ImportError:
            raise ImportError("To use the experience pool, you need to install the rag module.")

        persist_path = Path(self.config.exp_pool.persist_path)
        docstore_path = persist_path / "docstore.json"

        ranker_configs = self._get_ranker_configs()

        if not docstore_path.exists():
            logger.debug(f"Path `{docstore_path}` not exists, try to create a new bm25 storage.")
            exps = [Experience(req="req", resp="resp")]

            retriever_configs = [BM25RetrieverConfig(create_index=True, similarity_top_k=DEFAULT_SIMILARITY_TOP_K)]

            storage = SimpleEngine.from_objs(
                objs=exps, retriever_configs=retriever_configs, ranker_configs=ranker_configs
            )
            return storage

        logger.debug(f"Path `{docstore_path}` exists, try to load bm25 storage.")

View on GitHub (pinned to 11cdf466d0)

Solutions

1. Install the rag extras: pip install 'metagpt[rag]' — this pulls llama-index and the BM25/storage dependencies.
2. Alternatively install the required pieces directly (llama-index-core / llama-index-retrievers-bm25 per metagpt's rag extra spec) if you want a minimal env.
3. Rebuild your deployment image with the extra included so runtime imports never fail.

Example fix

# before
# pip install metagpt  (no extras)
await manager.get_by_req(req)  # ImportError: To use the experience pool, you need to install the rag module.

# after
# shell: pip install 'metagpt[rag]'
await manager.get_by_req(req)

def rag_module_available() -> bool:
    try:
        from metagpt.rag.engines import SimpleEngine  # noqa: F401
        from metagpt.rag.schema import BM25RetrieverConfig  # noqa: F401
        return True
    except ImportError:
        return False

assert rag_module_available(), "experience pool needs rag extras: pip install 'metagpt[rag]'"

try:
    exps = await manager.get_by_req(req)
except ImportError as e:
    if "rag module" in str(e):
        raise SystemExit("exp pool BM25 backend requires rag extras: pip install 'metagpt[rag]'") from e
    raise

When it happens

Trigger: Configuring exp_pool with retriever type bm25 (or leaving the default) and calling a manager operation that builds the engine, in an environment where MetaGPT was installed without the rag extras.

Common situations: pip install metagpt (base) then turning on the experience pool; slim Docker images; upgrading metagpt and the rag extras were dropped; the BM25 path also wants a persisted docstore.json so first-run setups are common.

Related errors

• Please install pymilvus first.
• `req` must be provided as a keyword argument.
• Missing fields: {missing_fields}
• use `review` after `fill`
• Data type not supported for metadata extraction.

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