FoundationAgents/MetaGPT · error · ValueError

Creator not registered for key: {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.

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)

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.