crewAIInc/crewAI · critical · ValueError

BRIGHT_DATA_API_KEY environment variable is required.

Error message

BRIGHT_DATA_API_KEY environment variable is required.

What it means

Raised by BrightDataSERPTool.__init__ when BRIGHT_DATA_API_KEY is not in the environment. Unlike the dataset tool, the SERP tool validates at construction time and stores self.api_key / self.zone for its requests to the SERP API URL from config.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/brightdata_tool/brightdata_serp.py:128

        search_type: str | None = None,
        device_type: str = "desktop",
        parse_results: bool = True,
        **kwargs: Any,
    ):
        super().__init__(**kwargs)
        self.base_url = self._config.API_URL
        self.query = query
        self.search_engine = search_engine
        self.country = country
        self.language = language
        self.search_type = search_type
        self.device_type = device_type
        self.parse_results = parse_results

        self.api_key = os.getenv("BRIGHT_DATA_API_KEY") or ""
        self.zone = os.getenv("BRIGHT_DATA_ZONE") or ""
        if not self.api_key:
            raise ValueError("BRIGHT_DATA_API_KEY environment variable is required.")
        if not self.zone:
            raise ValueError("BRIGHT_DATA_ZONE environment variable is required.")

    def get_search_url(self, engine: str, query: str) -> str:
        if engine == "yandex":
            return f"https://yandex.com/search/?text=${query}"
        if engine == "bing":
            return f"https://www.bing.com/search?q=${query}"
        return f"https://www.google.com/search?q=${query}"

    def _run(
        self,
        query: str | None = None,
        search_engine: str | None = None,
        country: str | None = None,
        language: str | None = None,
        search_type: str | None = None,
        device_type: str | None = None,

View on GitHub (pinned to 754d7323be)

Solutions

Set BRIGHT_DATA_API_KEY before creating the tool (export or load_dotenv at app startup).
For services, pass the env through explicitly: Environment=BRIGHT_DATA_API_KEY=... in systemd, -e in docker run.
Restart notebook/worker kernels after adding the variable so they inherit it.

Example fix

# before
tool = BrightDataSERPTool()  # ValueError at __init__

# after
from dotenv import load_dotenv
load_dotenv()
from crewai_tools.tools.brightdata_tool import BrightDataSERPTool
tool = BrightDataSERPTool(query='crewai', search_engine='google')

Defensive patterns

Strategy: validation

Validate before calling

import os
from dotenv import load_dotenv

load_dotenv()
missing = [v for v in ("BRIGHT_DATA_API_KEY", "BRIGHT_DATA_ZONE") if not os.getenv(v)]
if missing:
    raise SystemExit(f"Missing env vars: {missing}")

Try / catch

try:
    tool = BrightDataSERPTool(query='crewai')
except ValueError as e:
    if "environment variable is required" in str(e):
        load_dotenv()
        tool = BrightDataSERPTool(query='crewai')
    else:
        raise

Prevention

Construct SERP/unlocker tools once at startup, after env validation.
Check both BRIGHT_DATA_API_KEY and BRIGHT_DATA_ZONE together — the tool needs both.
Restart long-lived kernels/workers after adding env vars.

When it happens

Trigger: Instantiating BrightDataSERPTool() before the env var is exported; setting the variable after construction; running under a process manager (systemd, docker, celery worker) that drops interactive shell env.

Common situations: Constructor-time failure surprising users who set env later, multi-service deployments where only one service has the secret, notebook kernels started before the key was added.

Related errors

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/bceab1437ea66945. Report an issue: GitHub.