What causes "To use the similarity search, you need to install the RAG module." in FoundationAgents/MetaGPT?

Install the RAG extra: pip install -e.[rag] (or pip install metagpt[rag])

FoundationAgents/MetaGPT · error · ImportError

To use the similarity search, you need to install the RAG mo

Error message

To use the similarity search, you need to install the RAG module.

What it means

Raised by Editor.similarity_search when importing metagpt.tools.libs.index_repo fails, meaning the optional RAG dependencies (the llama-index based RAG module) are not installed. similarity_search delegates to IndexRepo.cross_repo_search, which requires the rag extra; the bare ImportError is re-raised with a clearer message.

Source

Thrown at metagpt/tools/libs/editor.py:1132

            query (str): The search query string to look for in the indexed files.
            path (Union[str, Path]): A pathname or filename to search within.

        Returns:
            List[str]: A list of results as strings, containing the text from the merged results
                        and any direct results from non-indexed files.

        Example:
            >>> query = "The problem to be analyzed from the document"
            >>> file_or_path = "The pathname or filename you want to search within"
            >>> texts: List[str] = await Editor.similarity_search(query=query, path=file_or_path)
            >>> print(texts)
        """
        try:
            from metagpt.tools.libs.index_repo import IndexRepo

            return await IndexRepo.cross_repo_search(query=query, file_or_path=path)
        except ImportError:
            raise ImportError("To use the similarity search, you need to install the RAG module.")

    @staticmethod
    def is_large_file(content: str, mix_token_count: int = 0) -> bool:
        encoding = tiktoken.get_encoding("cl100k_base")
        token_count = len(encoding.encode(content))
        mix_token_count = mix_token_count or DEFAULT_MIN_TOKEN_COUNT
        return token_count >= mix_token_count

View on GitHub (pinned to 11cdf466d0)

Solutions

Install the RAG extra: pip install -e.[rag] (or pip install metagpt[rag])
Verify with: python -c "from metagpt.tools.libs.index_repo import IndexRepo"
If you cannot install extras, use search_file/find_file (string search) instead of similarity search

Example fix

# before: ImportError raised at call time
await Editor.similarity_search(query=q, path=p)
# after
texts = await Editor.similarity_search(query=q, path=p)  # after: pip install -e.[rag]

Defensive patterns

Strategy: fallback

Validate before calling

try:
    from metagpt.tools.libs.index_repo import IndexRepo  # noqa: F401
    has_rag = True
except ImportError:
    has_rag = False

Try / catch

try:
    texts = await Editor.similarity_search(query=q, path=p)
except ImportError:
    texts = []  # fall back to editor.search_file(p) string search

Prevention

Install optional extras up front if you plan to use similarity search
Probe importability once at startup instead of failing mid-run
Keep a string-search fallback path for environments without RAG deps

When it happens

Trigger: Awaiting Editor.similarity_search(query=..., path=...) in an environment where MetaGPT was installed without the rag extra, so `from metagpt.tools.libs.index_repo import IndexRepo` raises ImportError.

Common situations: pip install metagpt (core only) then calling similarity search; a deployment image trimmed of optional deps; local editable install without extras.

Related errors

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