assafelovic/gpt-researcher · error · Exception

Google CX key not found. Please set the GOOGLE_CX_KEY enviro

Error message

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

What it means

Exception raised by the Google retriever's get_cx_key() when the GOOGLE_CX_KEY environment variable is missing. The CX key is the Custom Search Engine ID; without it Google search queries cannot be scoped and the retriever refuses to construct.

Source

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

        # 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):
        """
        Searches the query using Google Custom Search API, optionally restricting to specific domains
        Returns:
            list: List of search results with title, href and body
        """
        # Build query with domain restrictions if specified
        search_query = self.query
        if self.query_domains and len(self.query_domains) > 0:
            domain_query = " OR ".join([f"site:{domain}" for domain in self.query_domains])
            search_query = f"({domain_query}) {self.query}"

        print("Searching with query {0}...".format(search_query))

        # URL-encode every parameter. Interpolating the raw query broke any

View on GitHub (pinned to 6f998577d5)

Solutions

Create a Custom Search Engine at https://programmablesearchengine.google.com/ and copy its ID.
export GOOGLE_CX_KEY=<engine id> (add to .env).
Restart the app so the new variable is loaded before retriever creation.

Example fix

# before
# .env has only GOOGLE_API_KEY
retriever = Google(query="...")

# after
# .env
GOOGLE_API_KEY=...
GOOGLE_CX_KEY=a1b2c3d4e5f6g7h8i9
retriever = Google(query="...")

Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.environ.get("GOOGLE_CX_KEY"):
    raise SystemExit("Set GOOGLE_CX_KEY to your Programmable Search Engine ID")

Type guard

null

Try / catch

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

Prevention

Create the Programmable Search Engine first, then copy its cx id into env.
Pair it with GOOGLE_API_KEY in the same config block.
Preflight both variables at startup.

When it happens

Trigger: Instantiating the Google retriever with GOOGLE_API_KEY set but GOOGLE_CX_KEY absent; __init__ calls get_cx_key() which raises.

Common situations: Developer sets only the API key and forgets the search-engine ID, or the CX var name is mistyped in .env/compose.

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/22099e216f9294f0. Report an issue: GitHub.