crewAIInc/crewAI · critical · ValueError

BRIGHT_DATA_API_KEY environment variable is required.

Error message

BRIGHT_DATA_API_KEY environment variable is required.

What it means

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.

Source

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

    )

    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 = {

View on GitHub (pinned to 754d7323be)

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).

Example fix

# before
tool = BrightDataUnlockerTool()  # ValueError

# after
from dotenv import load_dotenv
load_dotenv()
from crewai_tools.tools.brightdata_tool import BrightDataUnlockerTool
tool = BrightDataUnlockerTool(url='https://example.com', format='markdown')

Defensive patterns

Strategy: validation

Validate before calling

import os

if not os.getenv("BRIGHT_DATA_API_KEY"):
    raise SystemExit("BRIGHT_DATA_API_KEY required for BrightDataUnlockerTool")

Try / catch

try:
    tool = BrightDataUnlockerTool(url=url, data_format='markdown')
except ValueError as e:
    if "BRIGHT_DATA_API_KEY" in str(e):
        load_dotenv()
        tool = BrightDataUnlockerTool(url=url, data_format='markdown')
    else:
        raise

Prevention

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.

When it happens

Trigger: Instantiating BrightDataUnlockerTool() without the env var; key set after construction; key visible to the dev shell but not to the deployed process.

Common situations: Missing .env loading at startup, per-environment secrets not propagated, notebook kernels predating the key.

Related errors

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