FoundationAgents/MetaGPT · error · ValueError

Creator not registered for key

Error message

Creator not registered for key: {key}

What it means

GenericFactory.get_instance looks up a creator callable registered under the exact key you pass; if no creator was registered for that key, it delegates to _raise_for_key which throws ValueError('Creator not registered for key: ...'). In the RAG stack this typically means the retriever/ranker/embedding type you requested has no registered constructor in that factory.

Solutions

  1. Use only the config types the factory registers (e.g. VectorIndexRetrieverConfig, BM25RetrieverConfig, RerankRetrieverConfig, LLMRankerConfig).
  2. For custom retrievers, register a creator: factory.register(type(MyConfig), lambda cfg: MyRetriever(cfg)) before building the engine.
  3. Print factory._creators.keys() to see what is actually registered in your environment.
  4. Upgrade metagpt if the type you need was added in a later version.

Example fix

# before
engine = SimpleEngine.from_input(input_dir='./data', retriever_configs=[MyCustomRetrieverConfig()])
# ValueError: Creator not registered for key: ...

# after
from metagpt.rag.factories.retriever import get_retriever_factory  # illustrative
get_retriever_factory().register(MyCustomRetrieverConfig, lambda cfg: MyCustomRetriever(cfg))
engine = SimpleEngine.from_input(input_dir='./data', retriever_configs=[MyCustomRetrieverConfig()])
Defensive patterns

Strategy: validation

Validate before calling

def ensure_registered(factory, key):
    if key not in factory._creators:
        raise ValueError(
            f"{type(key).__name__} not registered; known: {list(map(str, factory._creators))}"
        )

for cfg in retriever_configs + ranker_configs:
    ensure_registered(factory, cfg)

Try / catch

try:
    engine = SimpleEngine.from_input(input_dir=d, retriever_configs=configs, ranker_configs=rankers)
except ValueError as e:
    if "Creator not registered" in str(e):
        register_custom_configs()  # factory.register(type(cfg), creator)
        engine = SimpleEngine.from_input(input_dir=d, retriever_configs=configs, ranker_configs=rankers)
    else:
        raise

Prevention

When it happens

Trigger: Passing a retriever_configs/ranker_configs entry whose type or enum value is not in the factory's registry, e.g. an exotic BaseRetrieverConfig subclass or a typo'd constant, when SimpleEngine builds its retrievers/rankers.

Common situations: Custom retriever configs added without registering a corresponding creator, version mismatches where supported types were renamed, or composing configs from llama-index extensions MetaGPT does not know.

Related errors

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

Appendix: source

Thrown at metagpt/rag/factories/base.py:32

        self._creators = creators or {}

    def get_instances(self, keys: list[Any], **kwargs) -> list[Any]:
        """Get instances by keys."""
        return [self.get_instance(key, **kwargs) for key in keys]

    def get_instance(self, key: Any, **kwargs) -> Any:
        """Get instance by key.

        Raise Exception if key not found.
        """
        creator = self._creators.get(key)
        if creator:
            return creator(**kwargs)

        self._raise_for_key(key)

    def _raise_for_key(self, key: Any):
        raise ValueError(f"Creator not registered for key: {key}")


class ConfigBasedFactory(GenericFactory):
    """Designed to get objects based on object type."""

    def get_instance(self, key: Any, **kwargs) -> Any:
        """Get instance by the type of key.

        Key is config, such as a pydantic model, call func by the type of key, and the key will be passed to func.
        Raise Exception if key not found.
        """
        creator = self._creators.get(type(key))
        if creator:
            return creator(key, **kwargs)

        self._raise_for_key(key)

    def _raise_for_key(self, key: Any):

View on GitHub (pinned to 11cdf466d0)