FoundationAgents/MetaGPT · error · ValueError

To use serpapi search engine, make sure you provide the `api

Error message

To use serpapi search engine, make sure you provide the `api_key` when constructing an object. You can obtain an API key from https://serpapi.com/.

What it means

ValueError from SerperAPIWrapper's model_validator (mode='before'): the constructor values contain neither api_key nor the deprecated serpapi_api_key alias. SerpAPI is a paid/keyed service, so the wrapper refuses to build without credentials. The legacy alias is honored with a DeprecationWarning.

Source

Thrown at metagpt/tools/search_engine_serpapi.py:39

            "engine": "google",
            "google_domain": "google.com",
            "gl": "us",
            "hl": "en",
        }
    )
    url: str = "https://serpapi.com/search"
    aiosession: Optional[aiohttp.ClientSession] = None
    proxy: Optional[str] = None

    @model_validator(mode="before")
    @classmethod
    def validate_serpapi(cls, values: dict) -> dict:
        if "serpapi_api_key" in values:
            values.setdefault("api_key", values["serpapi_api_key"])
            warnings.warn("`serpapi_api_key` is deprecated, use `api_key` instead", DeprecationWarning, stacklevel=2)

        if "api_key" not in values:
            raise ValueError(
                "To use serpapi search engine, make sure you provide the `api_key` when constructing an object. You can obtain"
                " an API key from https://serpapi.com/."
            )
        return values

    async def run(self, query, max_results: int = 8, as_string: bool = True, **kwargs: Any) -> str:
        """Run query through SerpAPI and parse result async."""
        result = await self.results(query, max_results)
        return self._process_response(result, as_string=as_string)

    async def results(self, query: str, max_results: int) -> dict:
        """Use aiohttp to run query through SerpAPI and return the results async."""

        params = self.get_params(query)
        params["source"] = "python"
        params["num"] = max_results
        params["output"] = "json"

View on GitHub (pinned to 11cdf466d0)

Solutions

1. Pass the key: SerpAPIWrapper(api_key=os.environ['SERPAPI_API_KEY'])
2. Or set api_key in your MetaGPT config for the serpapi engine
3. Legacy field serpapi_api_key still works (deprecation warning) if your config uses it

Example fix

# before
engine = SerperAPIWrapper()  # ValueError
# after
engine = SerperAPIWrapper(api_key=os.environ["SERPAPI_API_KEY"])

import os
api_key = os.environ.get("SERPAPI_API_KEY")
if not api_key:
    raise SystemExit("set SERPAPI_API_KEY before constructing SerperAPIWrapper")

try:
    engine = SerperAPIWrapper(api_key=k)
except ValueError as e:
    raise ConfigError(str(e))

When it happens

Trigger: SerpAPIWrapper() with no arguments; config selects serpapi as the search engine but the api key is absent from config and env; key intended to come from env but the variable was never loaded.

Common situations: Switching MetaGPT's SearchEngine to SerpAPI without setting SERPAPI_API_KEY; .env file not loaded in deployment; legacy config using serpapi_api_key removed during refactor.

Related errors

• To use google search engine, make sure you provide the `api_
• To use google search engine, make sure you provide the `cse_
• To use serper search engine, make sure you provide the `api_
• Got error from SerpAPI: {res['error']}
• Got error from SerpAPI: {res['error']}

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