assafelovic/gpt-researcher · error · Exception

SerpApi API key not found. Please set the SERPAPI_API_KEY en

Error message

SerpApi API key not found. Please set the SERPAPI_API_KEY environment variable. You can get a key at https://serpapi.com/

What it means

The SerpApi retriever requires an API key to authenticate with serpapi.com. During SerpApiRetriever construction, get_api_key() reads os.environ['SERPAPI_API_KEY'] and raises a plain Exception when the variable is absent. This is a configuration error that surfaces before any network call is made.

Source

Thrown at gpt_researcher/retrievers/serpapi/serpapi.py:32

        """
        Initializes the SerpApiSearch object
        Args:
            query:
        """
        self.query = query
        self.query_domains = query_domains or None
        self.api_key = self.get_api_key()

    def get_api_key(self):
        """
        Gets the SerpApi API key
        Returns:

        """
        try:
            api_key = os.environ["SERPAPI_API_KEY"]
        except Exception:
            raise Exception("SerpApi API key not found. Please set the SERPAPI_API_KEY environment variable. "
                            "You can get a key at https://serpapi.com/")
        return api_key

    def search(self, max_results=7):
        """
        Searches the query
        Returns:

        """
        print("SerpApiSearch: Searching with query {0}...".format(self.query))
        """Useful for general internet search queries using SerpApi."""

        url = "https://serpapi.com/search.json"

        search_query = self.query
        if self.query_domains:
            # Add site:domain1 OR site:domain2 OR ... to the search query
            search_query += " site:" + " OR site:".join(self.query_domains)

View on GitHub (pinned to 6f998577d5)

Solutions

Set the variable: export SERPAPI_API_KEY='your-key' (or add SERPAPI_API_KEY=... to .env and ensure it's loaded before constructing the retriever).
For Docker deployments, pass it with -e SERPAPI_API_KEY=... or in the compose environment section.
Get a valid key at https://serpapi.com if you don't have one.
Verify with python -c "import os; print(os.environ.get('SERPAPI_API_KEY'))" before running the app.

Example fix

# before
retriever = SerpApiRetriever(query='openai')  # raises: SerpApi API key not found

# after
import os
os.environ['SERPAPI_API_KEY'] = 'your-key'
retriever = SerpApiRetriever(query='openai')

Defensive patterns

Strategy: validation

Validate before calling

import os

if not os.environ.get('SERPAPI_API_KEY'):
    raise SystemExit('SERPAPI_API_KEY is not set — get a key at https://serpapi.com')

Try / catch

try:
    retriever = SerpApiRetriever(query='...')
except Exception as e:
    if 'API key not found' in str(e):
        # config problem, not transient — fix env and restart
        raise SystemExit(f'Config error: {e}')
    raise

Prevention

Load .env with python-dotenv at process start, before any retriever import side effects.
Centralize API keys in a settings object validated at startup so misconfig fails fast.
In Docker/CI, add a container init check that all required *_API_KEY vars are present.
Use a secrets manager or platform secrets rather than ad-hoc exports.

When it happens

Trigger: Instantiating the SerpApi retriever (directly or via GPT Researcher's retriever registry with retrieval provider 'serpapi') in a process where the SERPAPI_API_KEY environment variable is not set (including unset, empty-string counts as set, but missing raises KeyError caught by the bare except).

Common situations: Running in a fresh shell/CI container without exporting the var; .env file not loaded because python-dotenv was never invoked; deploying to Docker/systemd where env vars from the local shell don't propagate; typos like SERP_API_KEY.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of assafelovic/gpt-researcher@6f998577d5 (2026-08-28). Data as JSON: /api/errors/7af1e2064dd0f763. Report an issue: GitHub.