What causes "To use RAG, please set your embedding in config2.yaml." in FoundationAgents/MetaGPT?

Add an embedding section to config2.yaml, e.g. embedding: {api_type: openai, api_key: ..., base_url: ...}.

FoundationAgents/MetaGPT · error · TypeError

To use RAG, please set your embedding in config2.yaml.

Error message

To use RAG, please set your embedding in config2.yaml.

What it means

RAGEmbedding._resolve_embedding_type needs to know which embedding backend to build. It first checks config.embedding.api_type; if unset it falls back to the LLM api_type but only when that is OPENAI or AZURE (backward compatibility). Any other LLM backend with no explicit embedding config raises TypeError telling you to set embedding in config2.yaml.

Source

Thrown at metagpt/rag/factories/embedding.py:50

        self.config = config if config else Config.default()

    def get_rag_embedding(self, key: EmbeddingType = None) -> BaseEmbedding:
        """Key is EmbeddingType."""
        return super().get_instance(key or self._resolve_embedding_type())

    def _resolve_embedding_type(self) -> EmbeddingType | LLMType:
        """Resolves the embedding type.

        If the embedding type is not specified, for backward compatibility, it checks if the LLM API type is either OPENAI or AZURE.
        Raise TypeError if embedding type not found.
        """
        if self.config.embedding.api_type:
            return self.config.embedding.api_type

        if self.config.llm.api_type in [LLMType.OPENAI, LLMType.AZURE]:
            return self.config.llm.api_type

        raise TypeError("To use RAG, please set your embedding in config2.yaml.")

    def _create_openai(self) -> "OpenAIEmbedding":
        from llama_index.embeddings.openai import OpenAIEmbedding

        params = dict(
            api_key=self.config.embedding.api_key or self.config.llm.api_key,
            api_base=self.config.embedding.base_url or self.config.llm.base_url,
        )

        self._try_set_model_and_batch_size(params)

        return OpenAIEmbedding(**params)

    def _create_azure(self) -> AzureOpenAIEmbedding:
        params = dict(
            api_key=self.config.embedding.api_key or self.config.llm.api_key,
            azure_endpoint=self.config.embedding.base_url or self.config.llm.base_url,
            api_version=self.config.embedding.api_version or self.config.llm.api_version,

View on GitHub (pinned to 11cdf466d0)

Solutions

Add an embedding section to config2.yaml, e.g. embedding: {api_type: openai, api_key: ..., base_url: ...}.
Point embedding at a provider that matches your stack (AzureOpenAIEmbedding config, or a local embedding via the supported api types).
If your LLM is already OpenAI/Azure, ensure llm.api_type is exactly OPENAI/AZURE so the fallback applies.
Alternatively pass an explicit embed_model to SimpleEngine to bypass config resolution.

Example fix

# before (config2.yaml)
llm:
  api_type: zhipuai
  api_key: ...
# no embedding section -> TypeError on RAG usage

# after
embedding:
  api_type: openai
  api_key: "sk-..."
  base_url: "https://api.openai.com/v1"

Defensive patterns

Strategy: validation

Validate before calling

from metagpt.const import LLMType

def embedding_resolvable(config) -> bool:
    if config.embedding and config.embedding.api_type:
        return True
    return config.llm.api_type in (LLMType.OPENAI, LLMType.AZURE)

assert embedding_resolvable(config), "set embedding.api_type in config2.yaml before using RAG"

Try / catch

try:
    engine = SimpleEngine.from_input(input_dir='./data')
except TypeError as e:
    if "embedding in config2.yaml" in str(e):
        raise SystemExit("Add an embedding: {api_type: openai, api_key: ...} section to config2.yaml") from e
    raise

Prevention

Always define the embedding block when using RAG with non-OpenAI LLMs
Pass an explicit embed_model to SimpleEngine to bypass config resolution
Add a startup check that embedding.api_type is set when RAG features are enabled

When it happens

Trigger: Using RAG with api_type like 'qianfan', 'zhipuai', 'gemini', or a local LLM while the embedding: section of config2.yaml is absent or has no api_type; from_input/from_objs then tries to build the default embedding and this raises.

Common situations: Switching the project's LLM to a non-OpenAI provider and assuming embeddings follow, fresh config2.yaml missing the embedding block, or embedding.api_key present but api_type omitted.

Related errors

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