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 BrightDataUnlockerTool.__init__ when BRIGHT_DATA_ZONE is not set. The zone (a named Web Unlocker zone in the Bright Data account) is sent in the request payload and selects routing/behavior; the constructor refuses to build the tool without it, same as the SERP tool.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/brightdata_tool/brightdata_unlocker.py:104

    def __init__(
        self,
        url: str | None = None,
        format: str = "raw",
        data_format: str = "markdown",
        **kwargs: Any,
    ):
        super().__init__(**kwargs)
        self.base_url = self._config.API_URL
        self.url = url
        self.format = format
        self.data_format = data_format

        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 _run(
        self,
        url: str | None = None,
        format: str | None = None,
        data_format: str | None = None,
        **kwargs: Any,
    ) -> Any:
        url = url or self.url
        format = format or self.format
        data_format = data_format or self.data_format

        if not url:
            raise ValueError("url is required either in constructor or method call")

        payload = {
            "url": url,
            "zone": self.zone,

View on GitHub (pinned to 754d7323be)

Solutions

1. Create a Web Unlocker zone in Bright Data and export BRIGHT_DATA_ZONE=<zone_id>.
2. Verify with: python -c "import os; print(os.getenv('BRIGHT_DATA_ZONE'))".
3. Add both BRIGHT_DATA_* variables to your service/CI environment definition.

Example fix

# shell
export BRIGHT_DATA_API_KEY='...'
export BRIGHT_DATA_ZONE='unlocker_zone'

# python
from crewai_tools.tools.brightdata_tool import BrightDataUnlockerTool
tool = BrightDataUnlockerTool(url='https://example.com', data_format='markdown')

import os

for var in ("BRIGHT_DATA_API_KEY", "BRIGHT_DATA_ZONE"):
    if not os.getenv(var):
        raise SystemExit(f"Missing {var}; create the zone in Bright Data and export it")

try:
    tool = BrightDataUnlockerTool(url=url)
except ValueError as e:
    if "BRIGHT_DATA_ZONE" in str(e):
        raise SystemExit("Set BRIGHT_DATA_ZONE to your Web Unlocker zone id")
    raise

When it happens

Trigger: Constructing BrightDataUnlockerTool with the API key set but no BRIGHT_DATA_ZONE; zone not yet created in the Bright Data dashboard; env var name mismatch.

Common situations: New Bright Data accounts that have a token but no unlocked zone configured, deployment environments missing the second variable, typos such as BRIGHTDATA_ZONE.

Related errors

• BRIGHT_DATA_ZONE environment variable is required.
• BRIGHT_DATA_API_KEY environment variable is required.
• BRIGHT_DATA_API_KEY environment variable is required.
• BRIGHT_DATA_API_KEY environment variable is required.
• url is required either in constructor or method call

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