What causes "Model '{model}' not found in configuration" in FoundationAgents/MetaGPT?

Use a model name exactly as defined in the models configuration registry

FoundationAgents/MetaGPT · error · ValueError

Model '{model}' not found in configuration

Error message

Model '{model}' not found in configuration

What it means

Raised by _load_llm_config when ModelsConfig.default().get(model) returns None (the name is absent from the loaded models registry) or raises AttributeError (the registry itself failed to load, e.g. missing/malformed models config file). Both are converted to this ValueError naming the offending model.

Source

Thrown at metagpt/ext/spo/utils/llm_client.py:38

    def __init__(
        self,
        optimize_kwargs: Optional[dict] = None,
        evaluate_kwargs: Optional[dict] = None,
        execute_kwargs: Optional[dict] = None,
    ) -> None:
        self.evaluate_llm = LLM(llm_config=self._load_llm_config(evaluate_kwargs))
        self.optimize_llm = LLM(llm_config=self._load_llm_config(optimize_kwargs))
        self.execute_llm = LLM(llm_config=self._load_llm_config(execute_kwargs))

    def _load_llm_config(self, kwargs: dict) -> Any:
        model = kwargs.get("model")
        if not model:
            raise ValueError("'model' parameter is required")

        try:
            model_config = ModelsConfig.default().get(model)
            if model_config is None:
                raise ValueError(f"Model '{model}' not found in configuration")

            config = model_config.model_copy()

            for key, value in kwargs.items():
                if hasattr(config, key):
                    setattr(config, key, value)

            return config

        except AttributeError:
            raise ValueError(f"Model '{model}' not found in configuration")
        except Exception as e:
            raise ValueError(f"Error loading configuration for model '{model}': {str(e)}")

    async def responser(self, request_type: RequestType, messages: List[dict]) -> str:
        llm_mapping = {
            RequestType.OPTIMIZE: self.optimize_llm,
            RequestType.EVALUATE: self.evaluate_llm,

View on GitHub (pinned to 11cdf466d0)

Solutions

Use a model name exactly as defined in the models configuration registry
Add your custom model entry to the models config file and retry
If the error comes from the AttributeError path, verify the models config file exists and is valid YAML at the expected path

Example fix

# before
evaluate_kwargs={"model": "gpt4o"}

# after
evaluate_kwargs={"model": "gpt-4o"}

Defensive patterns

Strategy: validation

Validate before calling

from metagpt.utils.models_config import ModelsConfig
names = list(ModelsConfig.default().models.keys()) if hasattr(ModelsConfig.default(), "models") else None
if ModelsConfig.default().get(model) is None:
    raise ValueError(f"register '{model}' in models config first")

Type guard

def model_is_registered(model: str) -> bool:
    from metagpt.utils.models_config import ModelsConfig
    cfg = ModelsConfig.default()
    return cfg.get(model) is not None

Prevention

Copy model names verbatim from the models config registry
Add custom models to the models yaml before referencing them
If the AttributeError path fires, verify the models config file exists and parses

When it happens

Trigger: Passing a model name that is not defined in the models configuration file (typo, custom model not registered), or the ModelsConfig source file being absent so .default()/.get fails with AttributeError.

Common situations: Misspelled model names; using a private/local model without adding it to the models yaml; upgrading MetaGPT changed the models config location/format so default() cannot load it.

Related errors

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