{"record":{"id":"f1bd69f3cb57de27","repo":"FoundationAgents/MetaGPT","slug":"to-use-the-experience-pool-you-need-to-install-th","errorCode":null,"errorMessage":"To use the experience pool, you need to install the rag module.","messagePattern":"To use the experience pool, you need to install the rag module\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"metagpt/exp_pool/manager.py","lineNumber":163,"sourceCode":"    def _create_bm25_storage(self) -> \"SimpleEngine\":\n        \"\"\"Creates or loads BM25 storage.\n\n        This function attempts to create a new BM25 storage if the specified\n        document store path does not exist. If the path exists, it loads the\n        existing BM25 storage.\n\n        Returns:\n            SimpleEngine: An instance of SimpleEngine configured with BM25 storage.\n\n        Raises:\n            ImportError: If required modules are not installed.\n        \"\"\"\n\n        try:\n            from metagpt.rag.engines import SimpleEngine\n            from metagpt.rag.schema import BM25IndexConfig, BM25RetrieverConfig\n        except ImportError:\n            raise ImportError(\"To use the experience pool, you need to install the rag module.\")\n\n        persist_path = Path(self.config.exp_pool.persist_path)\n        docstore_path = persist_path / \"docstore.json\"\n\n        ranker_configs = self._get_ranker_configs()\n\n        if not docstore_path.exists():\n            logger.debug(f\"Path `{docstore_path}` not exists, try to create a new bm25 storage.\")\n            exps = [Experience(req=\"req\", resp=\"resp\")]\n\n            retriever_configs = [BM25RetrieverConfig(create_index=True, similarity_top_k=DEFAULT_SIMILARITY_TOP_K)]\n\n            storage = SimpleEngine.from_objs(\n                objs=exps, retriever_configs=retriever_configs, ranker_configs=ranker_configs\n            )\n            return storage\n\n        logger.debug(f\"Path `{docstore_path}` exists, try to load bm25 storage.\")","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/FoundationAgents/MetaGPT/blob/11cdf466d042aece04fc6cfd13b28e1a70341b1f/metagpt/exp_pool/manager.py#L145-L181","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install the rag extras: pip install 'metagpt[rag]' — this pulls llama-index and the BM25/storage dependencies.","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.","Rebuild your deployment image with the extra included so runtime imports never fail."],"exampleFix":"# before\n# pip install metagpt  (no extras)\nawait manager.get_by_req(req)  # ImportError: To use the experience pool, you need to install the rag module.\n\n# after\n# shell: pip install 'metagpt[rag]'\nawait manager.get_by_req(req)","handlingStrategy":"validation","validationCode":"def rag_module_available() -> bool:\n    try:\n        from metagpt.rag.engines import SimpleEngine  # noqa: F401\n        from metagpt.rag.schema import BM25RetrieverConfig  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nassert rag_module_available(), \"experience pool needs rag extras: pip install 'metagpt[rag]'\"","typeGuard":null,"tryCatchPattern":"try:\n    exps = await manager.get_by_req(req)\nexcept ImportError as e:\n    if \"rag module\" in str(e):\n        raise SystemExit(\"exp pool BM25 backend requires rag extras: pip install 'metagpt[rag]'\") from e\n    raise","preventionTips":["Install 'metagpt[rag]' whenever the experience pool is enabled in config.","Run a startup import probe for metagpt.rag before enabling exp_pool so failures are loud at boot.","Keep deployment requirements pinned with the rag extra — do not rely on the base metagpt wheel."],"tags":["python","exp-pool","missing-dependency","bm25","installation"],"backgroundTag":null,"analyzedSha":"11cdf466d042aece04fc6cfd13b28e1a70341b1f","analyzedAt":"2026-08-14T23:20:02.994Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}