ScrapeGraphAI/Scrapegraph-ai · error · SearchConfigError

Serper API key is required

Error message

Serper API key is required

What it means

Raised by the Serper backend when search_on_web is configured to use serper but no API key was provided. It is a configuration validation error raised before any network call.

Source

Thrown at scrapegraphai/utils/research_web.py:389

def _search_serper(
    query: str, max_results: int, api_key: str, timeout: int
) -> List[str]:
    """
    Helper function for Serper search.

    Args:
        query (str): Search query
        max_results (int): Maximum number of results to return
        api_key (str): API key for Serper
        timeout (int): Request timeout in seconds

    Returns:
        List[str]: List of URLs from search results
    """
    if not api_key:
        raise SearchConfigError("Serper API key is required")

    headers = {"X-API-KEY": api_key, "Content-Type": "application/json"}

    data = {"q": query, "num": max_results}

    try:
        response = requests.post(
            "https://google.serper.dev/search",
            json=data,
            headers=headers,
            timeout=timeout,
        )
        response.raise_for_status()

        json_data = response.json()
        results = []

        # Extract organic search results

View on GitHub (pinned to 532dfffbf6)

Solutions

1. Set serper_api_key in the SearchConfig (typically os.getenv('SERPER_APIKEY'))
2. Verify the env var name matches your .env
3. If you didn't intend to use serper, change search_engine back to google/duckduckgo

Example fix

// before
config = SearchConfig(query="x", search_engine="serper")
// after
config = SearchConfig(query="x", search_engine="serper", serper_api_key=os.getenv("SERPER_APIKEY"))

if config.search_engine == "serper":
    assert os.getenv("SERPER_APIKEY"), "SERPER_APIKEY not set"
    config.serper_api_key = os.getenv("SERPER_APIKEY")

try:
    results = search_on_web(config)
except SearchConfigError as e:
    if "API key" in str(e):
        config.serper_api_key = os.getenv("SERPER_APIKEY")
        results = search_on_web(config)
    else:
        raise

When it happens

Trigger: Calling search_on_web with search_engine='serper' and serper_api_key empty/None/whitespace in the SearchConfig.

Common situations: Forgetting to set the SERPER_API_KEY environment variable; passing the key under the wrong config attribute name; key read from .env that isn't loaded.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

• The 'graphviz' library is required for this functionality. P
• The browserbase module is not installed. Please install it u
• undetected_chromedriver is required for ChromiumLoader. Plea
• Cannot deep copy object of type {type(obj)}
• Unsupported service tier {service_tier!r} for {model_name}

AI-assisted analysis of ScrapeGraphAI/Scrapegraph-ai@532dfffbf6 (2026-08-28). Data as JSON: /api/errors/cbd01f26b5340e41. Report an issue: GitHub.