What causes "BRIGHT_DATA_ZONE environment variable is required." in crewAIInc/crewAI?

Create/locate a zone in the Bright Data dashboard (e.g. a SERP API zone) and export BRIGHT_DATA_ZONE= .

crewAIInc/crewAI · critical · ValueError

BRIGHT_DATA_ZONE environment variable is required.

Error message

BRIGHT_DATA_ZONE environment variable is required.

What it means

Raised by BrightDataSERPTool.__init__ (and equivalently by BrightDataUnlockerTool) when BRIGHT_DATA_ZONE is missing. Bright Data routes requests through named zones (proxy/Web Unlocker/SERP API configurations); the tool needs both the API key and the zone name, and refuses construction without the zone.

Source

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

        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,
        parse_results: bool | None = None,
        **kwargs: Any,

View on GitHub (pinned to 754d7323be)

Solutions

Create/locate a zone in the Bright Data dashboard (e.g. a SERP API zone) and export BRIGHT_DATA_ZONE=<zone_name>.
Confirm both variables in the same shell/process: env | grep BRIGHT_DATA.
For Docker/CI, add BRIGHT_DATA_ZONE alongside BRIGHT_DATA_API_KEY in the environment.

Example fix

# before
export BRIGHT_DATA_API_KEY=...  # zone missing -> ValueError

# after
export BRIGHT_DATA_API_KEY=...
export BRIGHT_DATA_ZONE=serp_api_zone
python -c "from crewai_tools.tools.brightdata_tool import BrightDataSERPTool; BrightDataSERPTool()"

Defensive patterns

Strategy: validation

Validate before calling

import os

REQUIRED_BRIGHTDATA = ("BRIGHT_DATA_API_KEY", "BRIGHT_DATA_ZONE")

def brightdata_env_ready() -> bool:
    return all(os.getenv(v) for v in REQUIRED_BRIGHTDATA)

if not brightdata_env_ready():
    raise SystemExit(f"Set both: {REQUIRED_BRIGHTDATA}")

Try / catch

try:
    tool = BrightDataSERPTool(query='crewai')
except ValueError as e:
    if "BRIGHT_DATA_ZONE" in str(e):
        raise SystemExit("Create a SERP zone in Bright Data and export BRIGHT_DATA_ZONE")
    raise

Prevention

Create the zone in the Bright Data dashboard first; the key alone is not enough.
Pair both variables in one env file so they are never set independently.
Name the check in a shared helper reused by SERP and unlocker tools.

When it happens

Trigger: Instantiating BrightDataSERPTool or BrightDataUnlockerTool with BRIGHT_DATA_API_KEY set but BRIGHT_DATA_ZONE unset; zone name typo (BRIGHT_DATA_ZONES); not having created a SERP zone in the Bright Data dashboard.

Common situations: Users configure the API key but skip zone creation; zone env var only set in deployment env; copy-paste setups from other Bright Data tooling that uses different variable names.

Related errors

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