assafelovic/gpt-researcher · error · Exception

Exa API key not found. Please set the EXA_API_KEY environmen

Error message

Exa API key not found. Please set the EXA_API_KEY environment variable. You can obtain your key from https://exa.ai/

What it means

Exception raised by the Exa retriever when the EXA_API_KEY environment variable is absent (KeyError on os.environ lookup). Exa (formerly Metaphor) requires a bearer key for every search request.

Source

Thrown at gpt_researcher/retrievers/exa/exa.py:35

        check_pkg("exa_py")
        from exa_py import Exa
        self.query = query
        self.api_key = self._retrieve_api_key()
        self.client = Exa(api_key=self.api_key)
        self.query_domains = query_domains or None

    def _retrieve_api_key(self):
        """
        Retrieves the Exa API key from environment variables.
        Returns:
            The API key.
        Raises:
            Exception: If the API key is not found.
        """
        try:
            api_key = os.environ["EXA_API_KEY"]
        except KeyError:
            raise Exception(
                "Exa API key not found. Please set the EXA_API_KEY environment variable. "
                "You can obtain your key from https://exa.ai/"
            )
        return api_key

    def search(
        self, max_results=10, use_autoprompt=False, search_type="neural", **filters
    ):
        """
        Searches the query using the Exa API.
        Args:
            max_results: The maximum number of results to return.
            use_autoprompt: Whether to use autoprompting.
            search_type: The type of search (e.g., "neural", "keyword").
            **filters: Additional filters (e.g., date range, domains).
        Returns:
            A list of search results.
        """

View on GitHub (pinned to 6f998577d5)

Solutions

export EXA_API_KEY=<key> (obtain at https://exa.ai).
Add EXA_API_KEY to .env / your secret manager and ensure it loads before retriever creation.
In CI/CD, add it as a masked environment variable.

Example fix

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

# after
import os
if not os.environ.get("EXA_API_KEY"):
    raise SystemExit("EXA_API_KEY missing — get one at https://exa.ai/")
retriever = Exa(query="...")

Defensive patterns

Strategy: validation

Validate before calling

import os
if not os.environ.get("EXA_API_KEY"):
    raise SystemExit("Set EXA_API_KEY (https://exa.ai)")

Type guard

null

Try / catch

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

Prevention

Add EXA_API_KEY to your secret store and startup preflight.
Confirm the var is present in the process env (printenv) after deploying.

When it happens

Trigger: Constructing the Exa retriever; __init__ calls _retrieve_api_key(), which raises when EXA_API_KEY is not set.

Common situations: Missing export, .env not loaded, key set only in local shell but app runs under a different user/service, or CI pipeline lacking the secret.

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/983bef8f8f01d6b7. Report an issue: GitHub.