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 BrightDataDatasetTool._run when the BRIGHT_DATA_API_KEY environment variable is empty/missing. The tool reads the key only from the environment at call time (not from the constructor), so every dataset run requires it to be set beforehand.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/brightdata_tool/brightdata_dataset.py:580

        zipcode = zipcode or self.zipcode
        additional_params = additional_params or self.additional_params

        if not dataset_type:
            raise ValueError(
                "dataset_type is required either in constructor or method call"
            )
        if not url:
            raise ValueError("url is required either in constructor or method call")

        valid_output_formats = {"json", "ndjson", "jsonl", "csv"}
        if output_format not in valid_output_formats:
            raise ValueError(
                f"Unsupported output format: {output_format}. Must be one of {', '.join(valid_output_formats)}."
            )

        api_key = os.getenv("BRIGHT_DATA_API_KEY")
        if not api_key:
            raise ValueError("BRIGHT_DATA_API_KEY environment variable is required.")

        try:
            return asyncio.run(
                self.get_dataset_data_async(
                    dataset_type=dataset_type,
                    output_format=output_format,
                    url=url,
                    zipcode=zipcode,
                    additional_params=additional_params,
                )
            )
        except TimeoutError as e:
            return f"Timeout Exception occured in method : get_dataset_data_async. Details - {e!s}"
        except BrightDataDatasetToolException as e:
            return (
                f"Exception occured in method : get_dataset_data_async. Details - {e!s}"
            )
        except Exception as e:

View on GitHub (pinned to 754d7323be)

Solutions

1. export BRIGHT_DATA_API_KEY=<token from Bright Data account settings>.
2. Call load_dotenv() before invoking the tool if the key lives in a .env file.
3. Inject via Docker (-e) or your platform's secret manager for deployments.
4. Prefer os.environ['BRIGHT_DATA_API_KEY'] lookups over shell-only exports for reproducibility.

Example fix

# before
result = tool.run(url=url, dataset_type='amazon_product')  # ValueError

# after
import os
from dotenv import load_dotenv
load_dotenv()
if not os.getenv('BRIGHT_DATA_API_KEY'):
    raise SystemExit('Missing BRIGHT_DATA_API_KEY')
result = tool.run(url=url, dataset_type='amazon_product')

import os

if not os.getenv("BRIGHT_DATA_API_KEY"):
    raise SystemExit("BRIGHT_DATA_API_KEY must be set before running Bright Data dataset tools")

try:
    result = tool.run(url=url, dataset_type=dt)
except ValueError as e:
    if "BRIGHT_DATA_API_KEY" in str(e):
        load_dotenv()
        result = tool.run(url=url, dataset_type=dt)
    else:
        raise

When it happens

Trigger: Running the tool without exporting BRIGHT_DATA_API_KEY; the variable set in a parent process but not in the container/notebook kernel executing the tool; key name typo (e.g. BRIGHTDATA_API_KEY).

Common situations: .env not loaded, secrets configured per-environment but the code runs elsewhere, CI pipelines missing the env var.

Related errors

• API key must be provided either through constructor or MINDS
• BRAVE_API_KEY environment variable is required for BraveSear
• BRIGHT_DATA_API_KEY environment variable is required.
• BRIGHT_DATA_ZONE environment variable is required.
• BRIGHT_DATA_API_KEY environment variable is required.

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