assafelovic/gpt-researcher · error · Exception

Google API key not found. Please set the GOOGLE_API_KEY envi

Error message

Google API key not found. Please set the GOOGLE_API_KEY environment variable. You can get a key at https://developers.google.com/custom-search/v1/overview

What it means

Exception raised by the Google retriever when the GOOGLE_API_KEY environment variable is missing (any failure of the os.environ lookup is caught and re-raised). Google Custom Search JSON API requires this key alongside the CX id.

Source

Thrown at gpt_researcher/retrievers/google/google.py:36

            query:
        """
        self.query = query
        self.headers = headers or {}
        self.query_domains = query_domains or None
        self.api_key = self.headers.get("google_api_key") or self.get_api_key()  # Use the passed api_key or fallback to environment variable
        self.cx_key = self.headers.get("google_cx_key") or self.get_cx_key()  # Use the passed cx_key or fallback to environment variable

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

        """
        # Get the API key
        try:
            api_key = os.environ["GOOGLE_API_KEY"]
        except Exception:
            raise Exception("Google API key not found. Please set the GOOGLE_API_KEY environment variable. "
                            "You can get a key at https://developers.google.com/custom-search/v1/overview")
        return api_key

    def get_cx_key(self):
        """
        Gets the Google CX key
        Returns:

        """
        # Get the API key
        try:
            api_key = os.environ["GOOGLE_CX_KEY"]
        except Exception:
            raise Exception("Google CX key not found. Please set the GOOGLE_CX_KEY environment variable. "
                            "You can get a key at https://developers.google.com/custom-search/v1/overview")
        return api_key

    def search(self, max_results=7):

View on GitHub (pinned to 6f998577d5)

Solutions

Create an API key in Google Cloud and export GOOGLE_API_KEY.
Also set GOOGLE_CX_KEY (the custom search engine id) — both are required.
Add both to .env and verify loading before retriever construction.

Example fix

# before
retriever = Google(query="...")

# after
import os
for var in ("GOOGLE_API_KEY", "GOOGLE_CX_KEY"):
    assert os.environ.get(var), f"{var} missing"
retriever = Google(query="...")

Defensive patterns

Strategy: validation

Validate before calling

import os
missing = [v for v in ("GOOGLE_API_KEY", "GOOGLE_CX_KEY") if not os.environ.get(v)]
if missing:
    raise SystemExit(f"Missing env vars: {missing}")

Type guard

null

Try / catch

try:
    retriever = Google(query)
except Exception as e:
    if "GOOGLE_API_KEY" in str(e) or "GOOGLE_CX_KEY" in str(e):
        sys.exit(str(e))
    raise

Prevention

Always set both GOOGLE_API_KEY and GOOGLE_CX_KEY together.
Validate both vars in a startup preflight.
Document the pair in deployment templates.

When it happens

Trigger: Instantiating the Google retriever; __init__ calls get_api_key(), which raises when GOOGLE_API_KEY is unset.

Common situations: Missing Google Cloud API key, .env not loaded, or only GOOGLE_CX_KEY set — both GOOGLE_API_KEY and GOOGLE_CX_KEY are needed.

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/98ec0b31b8fb3e82. Report an issue: GitHub.