What causes "'model' parameter is required" in FoundationAgents/MetaGPT?

Add a 'model' key to every kwargs dict passed for evaluate, optimize, and execute

FoundationAgents/MetaGPT · error · ValueError

'model' parameter is required

Error message

'model' parameter is required

What it means

Raised by the SPO LLM client's _load_llm_config when the kwargs dict for one of the three LLM roles (evaluate/optimize/execute) has no 'model' key. The model name is the primary lookup key into ModelsConfig, so it is mandatory for each role-specific config.

Source

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


class SPO_LLM:
    _instance: Optional["SPO_LLM"] = None

    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)}")

View on GitHub (pinned to 11cdf466d0)

Solutions

Add a 'model' key to every kwargs dict passed for evaluate, optimize, and execute
Use a model name that exists in your models config (see the next error) once the key is present
Check the example SPO config for the exact kwargs structure

Example fix

# before
llm = ...evaluate_kwargs={"temperature": 0.3}...

# after
llm = ...evaluate_kwargs={"model": "gpt-4o-mini", "temperature": 0.3}...

Defensive patterns

Strategy: validation

Validate before calling

for name, kw in (("evaluate", evaluate_kwargs), ("optimize", optimize_kwargs), ("execute", execute_kwargs)):
    assert kw and kw.get("model"), f"{name} kwargs must include 'model'"

Type guard

def kwargs_have_model(kwargs: dict | None) -> bool:
    return bool(kwargs) and bool(kwargs.get("model"))

Prevention

Fill all three kwargs dicts from config with model as a required key
Validate config presence for evaluate/optimize/execute LLMs before constructing the client

When it happens

Trigger: Constructing the client with evaluate_kwargs/optimize_kwargs/execute_kwargs dicts that omit 'model', or with None kwargs (None.get would raise earlier, but {} lacks 'model').

Common situations: Configuring only some of the three LLMs (e.g. setting optimize_kwargs but leaving evaluate_kwargs as an empty dict); YAML config where the model key was not indented under the right role.

Related errors

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