{"record":{"id":"d98e4a2f4970e8bb","repo":"crewAIInc/crewAI","slug":"bright-data-api-key-environment-variable-is-requir-d98e4a","errorCode":null,"errorMessage":"BRIGHT_DATA_API_KEY environment variable is required.","messagePattern":"BRIGHT_DATA_API_KEY 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":102,"sourceCode":"    )\n\n    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 = {","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/tools/brightdata_tool/brightdata_unlocker.py#L84-L120","documentation":"Raised by BrightDataUnlockerTool.__init__ when BRIGHT_DATA_API_KEY is absent from the environment. The unlocker tool posts {url, zone, format} to the Web Unlocker API with a Bearer token built from this key, and validates its presence at construction time.","triggerScenarios":"Instantiating BrightDataUnlockerTool() without the env var; key set after construction; key visible to the dev shell but not to the deployed process.","commonSituations":"Missing .env loading at startup, per-environment secrets not propagated, notebook kernels predating the key.","solutions":["export BRIGHT_DATA_API_KEY=<token> before constructing the tool.","Load it programmatically: from dotenv import load_dotenv; load_dotenv().","Wire the secret through your deployment platform (docker -e, k8s secret, CI env)."],"exampleFix":"# before\ntool = BrightDataUnlockerTool()  # ValueError\n\n# after\nfrom dotenv import load_dotenv\nload_dotenv()\nfrom crewai_tools.tools.brightdata_tool import BrightDataUnlockerTool\ntool = BrightDataUnlockerTool(url='https://example.com', format='markdown')","handlingStrategy":"validation","validationCode":"import os\n\nif not os.getenv(\"BRIGHT_DATA_API_KEY\"):\n    raise SystemExit(\"BRIGHT_DATA_API_KEY required for BrightDataUnlockerTool\")","typeGuard":null,"tryCatchPattern":"try:\n    tool = BrightDataUnlockerTool(url=url, data_format='markdown')\nexcept ValueError as e:\n    if \"BRIGHT_DATA_API_KEY\" in str(e):\n        load_dotenv()\n        tool = BrightDataUnlockerTool(url=url, data_format='markdown')\n    else:\n        raise","preventionTips":["Validate env at process start rather than at tool construction deep in a task.","Share one brightdata_env_ready() helper across SERP, unlocker, and dataset tools.","Keep secrets in .env excluded from VCS and loaded via python-dotenv."],"tags":["bright-data","environment-variables","api-key","web-unlocker"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}