{"record":{"id":"cbd01f26b5340e41","repo":"ScrapeGraphAI/Scrapegraph-ai","slug":"serper-api-key-is-required","errorCode":null,"errorMessage":"Serper API key is required","messagePattern":"Serper API key is required","errorType":"exception","errorClass":"SearchConfigError","httpStatus":null,"severity":"error","filePath":"scrapegraphai/utils/research_web.py","lineNumber":389,"sourceCode":"\n\ndef _search_serper(\n    query: str, max_results: int, api_key: str, timeout: int\n) -> List[str]:\n    \"\"\"\n    Helper function for Serper search.\n\n    Args:\n        query (str): Search query\n        max_results (int): Maximum number of results to return\n        api_key (str): API key for Serper\n        timeout (int): Request timeout in seconds\n\n    Returns:\n        List[str]: List of URLs from search results\n    \"\"\"\n    if not api_key:\n        raise SearchConfigError(\"Serper API key is required\")\n\n    headers = {\"X-API-KEY\": api_key, \"Content-Type\": \"application/json\"}\n\n    data = {\"q\": query, \"num\": max_results}\n\n    try:\n        response = requests.post(\n            \"https://google.serper.dev/search\",\n            json=data,\n            headers=headers,\n            timeout=timeout,\n        )\n        response.raise_for_status()\n\n        json_data = response.json()\n        results = []\n\n        # Extract organic search results","sourceCodeStart":371,"sourceCodeEnd":407,"githubUrl":"https://github.com/ScrapeGraphAI/Scrapegraph-ai/blob/532dfffbf6ee823a6c9cf8cfedc24a93bf026780/scrapegraphai/utils/research_web.py#L371-L407","documentation":"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.","triggerScenarios":"Calling search_on_web with search_engine='serper' and serper_api_key empty/None/whitespace in the SearchConfig.","commonSituations":"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.","solutions":["Set serper_api_key in the SearchConfig (typically os.getenv('SERPER_APIKEY'))","Verify the env var name matches your .env","If you didn't intend to use serper, change search_engine back to google/duckduckgo"],"exampleFix":"// before\nconfig = SearchConfig(query=\"x\", search_engine=\"serper\")\n// after\nconfig = SearchConfig(query=\"x\", search_engine=\"serper\", serper_api_key=os.getenv(\"SERPER_APIKEY\"))","handlingStrategy":"validation","validationCode":"if config.search_engine == \"serper\":\n    assert os.getenv(\"SERPER_APIKEY\"), \"SERPER_APIKEY not set\"\n    config.serper_api_key = os.getenv(\"SERPER_APIKEY\")","typeGuard":null,"tryCatchPattern":"try:\n    results = search_on_web(config)\nexcept SearchConfigError as e:\n    if \"API key\" in str(e):\n        config.serper_api_key = os.getenv(\"SERPER_APIKEY\")\n        results = search_on_web(config)\n    else:\n        raise","preventionTips":["Load .env at startup and assert required API keys","Centralize key lookup in one place (os.getenv)"],"tags":["config","api-key","serper"],"backgroundTag":"missing-api-key","analyzedSha":"532dfffbf6ee823a6c9cf8cfedc24a93bf026780","analyzedAt":"2026-08-28T15:19:38.821Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}