{"record":{"id":"bceab1437ea66945","repo":"crewAIInc/crewAI","slug":"bright-data-api-key-environment-variable-is-requir-bceab1","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_serp.py","lineNumber":128,"sourceCode":"        search_type: str | None = None,\n        device_type: str = \"desktop\",\n        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,","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/tools/brightdata_tool/brightdata_serp.py#L110-L146","documentation":"Raised by BrightDataSERPTool.__init__ when BRIGHT_DATA_API_KEY is not in the environment. Unlike the dataset tool, the SERP tool validates at construction time and stores self.api_key / self.zone for its requests to the SERP API URL from config.","triggerScenarios":"Instantiating BrightDataSERPTool() before the env var is exported; setting the variable after construction; running under a process manager (systemd, docker, celery worker) that drops interactive shell env.","commonSituations":"Constructor-time failure surprising users who set env later, multi-service deployments where only one service has the secret, notebook kernels started before the key was added.","solutions":["Set BRIGHT_DATA_API_KEY before creating the tool (export or load_dotenv at app startup).","For services, pass the env through explicitly: Environment=BRIGHT_DATA_API_KEY=... in systemd, -e in docker run.","Restart notebook/worker kernels after adding the variable so they inherit it."],"exampleFix":"# before\ntool = BrightDataSERPTool()  # ValueError at __init__\n\n# after\nfrom dotenv import load_dotenv\nload_dotenv()\nfrom crewai_tools.tools.brightdata_tool import BrightDataSERPTool\ntool = BrightDataSERPTool(query='crewai', search_engine='google')","handlingStrategy":"validation","validationCode":"import os\nfrom dotenv import load_dotenv\n\nload_dotenv()\nmissing = [v for v in (\"BRIGHT_DATA_API_KEY\", \"BRIGHT_DATA_ZONE\") if not os.getenv(v)]\nif missing:\n    raise SystemExit(f\"Missing env vars: {missing}\")","typeGuard":null,"tryCatchPattern":"try:\n    tool = BrightDataSERPTool(query='crewai')\nexcept ValueError as e:\n    if \"environment variable is required\" in str(e):\n        load_dotenv()\n        tool = BrightDataSERPTool(query='crewai')\n    else:\n        raise","preventionTips":["Construct SERP/unlocker tools once at startup, after env validation.","Check both BRIGHT_DATA_API_KEY and BRIGHT_DATA_ZONE together — the tool needs both.","Restart long-lived kernels/workers after adding env vars."],"tags":["bright-data","environment-variables","api-key","serp"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}