crewAIInc/crewAI · error · ValueError

Unsupported output format: {output_format}. Must be one of {

Error message

Unsupported output format: {output_format}. Must be one of {', '.join(valid_output_formats)}.

What it means

Raised in BrightDataDatasetTool._run when output_format (the `format` argument, falling back to self.format) is not one of {'json','ndjson','jsonl','csv'}. The value is forwarded verbatim as the format query param to the snapshot download endpoint, so unsupported values are rejected up front.

Source

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

        additional_params: dict[str, Any] | None = None,
        **kwargs: Any,
    ) -> Any:
        dataset_type = dataset_type or self.dataset_type
        output_format = format or self.format
        url = url or self.url
        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:

View on GitHub (pinned to 754d7323be)

Solutions

Use exactly one of: json, ndjson, jsonl, csv (lowercase).
Set a default in the constructor: BrightDataDatasetTool(..., format='json') so per-call omission is safe.
If you wanted markdown/html page content, use BrightDataUnlockerTool instead of the dataset tool.

Example fix

# before
tool.run(url=url, dataset_type='amazon_product', format='xlsx')

# after
tool.run(url=url, dataset_type='amazon_product', format='json')

Defensive patterns

Strategy: validation

Validate before calling

VALID_DATASET_FORMATS = {"json", "ndjson", "jsonl", "csv"}

output_format = (format or 'json').lower()
if output_format not in VALID_DATASET_FORMATS:
    raise ValueError(f"format must be one of {VALID_DATASET_FORMATS}")
result = tool.run(url=url, dataset_type=dt, format=output_format)

Type guard

def is_valid_dataset_format(v: object) -> bool:
    return isinstance(v, str) and v in {"json", "ndjson", "jsonl", "csv"}

Try / catch

try:
    result = tool.run(url=url, dataset_type=dt, format=format)
except ValueError as e:
    if "Unsupported output format" in str(e):
        result = tool.run(url=url, dataset_type=dt, format='json')
    else:
        raise

Prevention

Whitelist and lowercase user/agent-supplied format values before the call.
Set format='json' as the constructor default.
Use the unlocker tool (data_format html/markdown) when you want page content, not dataset exports.

When it happens

Trigger: Calling tool.run(..., format='md') or format='xlsx'; passing format=None when the constructor also had no format (None is not in the valid set); typo like 'JSON' with uppercase letters.

Common situations: Confusing this tool's format (API serialization) with the unlocker tool's data_format ('html'/'markdown'), case-sensitivity mistakes, no default format set in some versions.

Related errors

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