{"record":{"id":"883b0bac36c7fea0","repo":"crewAIInc/crewAI","slug":"bright-data-zone-environment-variable-is-required","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_serp.py","lineNumber":130,"sourceCode":"        parse_results: bool = True,\n        **kwargs: Any,\n    ):\n        super().__init__(**kwargs)\n        self.base_url = self._config.API_URL\n        self.query = query\n        self.search_engine = search_engine\n        self.country = country\n        self.language = language\n        self.search_type = search_type\n        self.device_type = device_type\n        self.parse_results = parse_results\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 get_search_url(self, engine: str, query: str) -> str:\n        if engine == \"yandex\":\n            return f\"https://yandex.com/search/?text=${query}\"\n        if engine == \"bing\":\n            return f\"https://www.bing.com/search?q=${query}\"\n        return f\"https://www.google.com/search?q=${query}\"\n\n    def _run(\n        self,\n        query: str | None = None,\n        search_engine: str | None = None,\n        country: str | None = None,\n        language: str | None = None,\n        search_type: str | None = None,\n        device_type: str | None = None,\n        parse_results: bool | None = None,\n        **kwargs: Any,","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/tools/brightdata_tool/brightdata_serp.py#L112-L148","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nexport BRIGHT_DATA_API_KEY=...  # zone missing -> ValueError\n\n# after\nexport BRIGHT_DATA_API_KEY=...\nexport BRIGHT_DATA_ZONE=serp_api_zone\npython -c \"from crewai_tools.tools.brightdata_tool import BrightDataSERPTool; BrightDataSERPTool()\"","handlingStrategy":"validation","validationCode":"import os\n\nREQUIRED_BRIGHTDATA = (\"BRIGHT_DATA_API_KEY\", \"BRIGHT_DATA_ZONE\")\n\ndef brightdata_env_ready() -> bool:\n    return all(os.getenv(v) for v in REQUIRED_BRIGHTDATA)\n\nif not brightdata_env_ready():\n    raise SystemExit(f\"Set both: {REQUIRED_BRIGHTDATA}\")","typeGuard":null,"tryCatchPattern":"try:\n    tool = BrightDataSERPTool(query='crewai')\nexcept ValueError as e:\n    if \"BRIGHT_DATA_ZONE\" in str(e):\n        raise SystemExit(\"Create a SERP zone in Bright Data and export BRIGHT_DATA_ZONE\")\n    raise","preventionTips":["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."],"tags":["bright-data","environment-variables","proxy-zone","configuration"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}