stanford-oval/storm · error · RuntimeError

You must supply a serper_search_api_key param or set environ

Error message

You must supply a serper_search_api_key param or set environment variable SERPER_API_KEY

What it means

The SerperRM module of knowledge-storm requires a serper.dev API key, accepted either as the serper_search_api_key constructor argument or the SERPER_API_KEY environment variable; lacking both raises RuntimeError at construction. Serper.dev is a paid Google-Search-Results API commonly used as STORM's retrieval source.

Source

Thrown at knowledge_storm/rm.py:454

        """
        super().__init__(k=k)
        self.usage = 0
        self.query_params = None
        self.ENABLE_EXTRA_SNIPPET_EXTRACTION = ENABLE_EXTRA_SNIPPET_EXTRACTION
        self.webpage_helper = WebPageHelper(
            min_char_count=min_char_count,
            snippet_chunk_size=snippet_chunk_size,
            max_thread_num=webpage_helper_max_threads,
        )

        if query_params is None:
            self.query_params = {"num": k, "autocorrect": True, "page": 1}
        else:
            self.query_params = query_params
            self.query_params.update({"num": k})
        self.serper_search_api_key = serper_search_api_key
        if not self.serper_search_api_key and not os.environ.get("SERPER_API_KEY"):
            raise RuntimeError(
                "You must supply a serper_search_api_key param or set environment variable SERPER_API_KEY"
            )

        elif self.serper_search_api_key:
            self.serper_search_api_key = serper_search_api_key

        else:
            self.serper_search_api_key = os.environ["SERPER_API_KEY"]

        self.base_url = "https://google.serper.dev"

    def serper_runner(self, query_params):
        self.search_url = f"{self.base_url}/search"

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

View on GitHub (pinned to fb951af774)

Solutions

Get a key at serper.dev and export it: export SERPER_API_KEY=your-key
Or pass it directly: SerperRM(serper_search_api_key='your-key', k=10)
Call load_dotenv() before construction if the key lives in .env
Add SERPER_API_KEY to your CI secret store

Example fix

// before
rm = SerperRM(k=3)  # RuntimeError: You must supply a serper_search_api_key ...
// after
import os
from dotenv import load_dotenv
load_dotenv()
rm = SerperRM(serper_search_api_key=os.environ['SERPER_API_KEY'], k=3)

Defensive patterns

Strategy: validation

Validate before calling

import os
from dotenv import load_dotenv
load_dotenv()
if not (os.getenv('SERPER_API_KEY')):
    raise SystemExit('Set SERPER_API_KEY (https://serper.dev) or pass serper_search_api_key=')
rm = SerperRM(serper_search_api_key=os.environ['SERPER_API_KEY'], k=3)

Type guard

def has_serper_key(key: str | None) -> bool:
    import os
    return bool(key or os.getenv('SERPER_API_KEY'))

Try / catch

try:
    rm = SerperRM(k=3)
except RuntimeError as e:
    if 'serper_search_api_key' in str(e):
        raise SystemExit('Missing SERPER_API_KEY — get one at serper.dev and export it')
    raise

Prevention

Call load_dotenv() as the first line of your entrypoint Store SERPER_API_KEY in CI/secret manager and fail fast at startup
Prefer the env var over hardcoding the key in source

When it happens

Trigger: Constructing SerperRM(...) with no key while SERPER_API_KEY is unset; passing serper_search_api_key='' or None and relying on an env var that was never exported (e.g. .env not loaded in the shell/CI).

Common situations: New serper.dev account key never exported; CI pipeline missing the SERPER_API_KEY secret; using python-dotenv but forgetting load_dotenv() before constructing SerperRM; key passed to a different parameter name.

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

AI-assisted analysis of stanford-oval/storm@fb951af774 (2026-08-28). Data as JSON: /api/errors/ee4442fd9789d30e. Report an issue: GitHub.