{"record":{"id":"f1834ef4238dd3c7","repo":"crewAIInc/crewAI","slug":"bright-data-zone-environment-variable-is-required-f1834e","errorCode":null,"errorMessage":"BRIGHT_DATA_ZONE environment variable is required.","messagePattern":"BRIGHT_DATA_ZONE environment variable is required\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"lib/crewai-tools/src/crewai_tools/tools/brightdata_tool/brightdata_unlocker.py","lineNumber":104,"sourceCode":"    def __init__(\n        self,\n        url: str | None = None,\n        format: str = \"raw\",\n        data_format: str = \"markdown\",\n        **kwargs: Any,\n    ):\n        super().__init__(**kwargs)\n        self.base_url = self._config.API_URL\n        self.url = url\n        self.format = format\n        self.data_format = data_format\n\n        self.api_key = os.getenv(\"BRIGHT_DATA_API_KEY\") or \"\"\n        self.zone = os.getenv(\"BRIGHT_DATA_ZONE\") or \"\"\n        if not self.api_key:\n            raise ValueError(\"BRIGHT_DATA_API_KEY environment variable is required.\")\n        if not self.zone:\n            raise ValueError(\"BRIGHT_DATA_ZONE environment variable is required.\")\n\n    def _run(\n        self,\n        url: str | None = None,\n        format: str | None = None,\n        data_format: str | None = None,\n        **kwargs: Any,\n    ) -> Any:\n        url = url or self.url\n        format = format or self.format\n        data_format = data_format or self.data_format\n\n        if not url:\n            raise ValueError(\"url is required either in constructor or method call\")\n\n        payload = {\n            \"url\": url,\n            \"zone\": self.zone,","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/tools/brightdata_tool/brightdata_unlocker.py#L86-L122","documentation":"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.","triggerScenarios":"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.","commonSituations":"New Bright Data accounts that have a token but no unlocked zone configured, deployment environments missing the second variable, typos such as BRIGHTDATA_ZONE.","solutions":["Create a Web Unlocker zone in Bright Data and export BRIGHT_DATA_ZONE=<zone_id>.","Verify with: python -c \"import os; print(os.getenv('BRIGHT_DATA_ZONE'))\".","Add both BRIGHT_DATA_* variables to your service/CI environment definition."],"exampleFix":"# shell\nexport BRIGHT_DATA_API_KEY='...'\nexport BRIGHT_DATA_ZONE='unlocker_zone'\n\n# python\nfrom crewai_tools.tools.brightdata_tool import BrightDataUnlockerTool\ntool = BrightDataUnlockerTool(url='https://example.com', data_format='markdown')","handlingStrategy":"validation","validationCode":"import os\n\nfor var in (\"BRIGHT_DATA_API_KEY\", \"BRIGHT_DATA_ZONE\"):\n    if not os.getenv(var):\n        raise SystemExit(f\"Missing {var}; create the zone in Bright Data and export it\")","typeGuard":null,"tryCatchPattern":"try:\n    tool = BrightDataUnlockerTool(url=url)\nexcept ValueError as e:\n    if \"BRIGHT_DATA_ZONE\" in str(e):\n        raise SystemExit(\"Set BRIGHT_DATA_ZONE to your Web Unlocker zone id\")\n    raise","preventionTips":["Use a Web Unlocker zone (not a SERP or proxy zone) for the unlocker tool.","Check env vars with one shared preflight function before building any Bright Data tool.","Add both variables to deployment manifests so environments stay in sync."],"tags":["bright-data","environment-variables","proxy-zone","web-unlocker"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}