A file path must be provided in 'csv_file' parameter to save

Error message

A file path must be provided in 'csv_file' parameter to save the CSV output.

What it means

When requesting CSV output from aggregated_report, detailed_report, or comparative_detailed_report, a destination path must be supplied via the csv_file parameter. Since csv_file defaults to None, choosing output_format='csv' without a path raises this ValueError because there is nowhere to write the file.

Source

Thrown at haystack/evaluation/eval_run_result.py:117

    @staticmethod
    def _handle_output(
        data: dict[str, list[Any]], output_format: Literal["json", "csv", "df"] = "csv", csv_file: str | None = None
    ) -> Union[str, "DataFrame", dict[str, list[Any]]]:
        """
        Handles output formatting based on `output_format`.

        :returns: DataFrame for 'df', dict for 'json', or confirmation message for 'csv'
        """
        if output_format == "json":
            return data

        if output_format == "df":
            pandas_import.check()
            return DataFrame(data)

        if output_format == "csv":
            if not csv_file:
                raise ValueError("A file path must be provided in 'csv_file' parameter to save the CSV output.")
            return EvaluationRunResult._write_to_csv(csv_file, data)

        raise ValueError(f"Invalid output format '{output_format}' provided. Choose from 'json', 'csv', or 'df'.")

    def aggregated_report(
        self, output_format: Literal["json", "csv", "df"] = "json", csv_file: str | None = None
    ) -> Union[dict[str, list[Any]], "DataFrame", str]:
        """
        Generates a report with aggregated scores for each metric.

        :param output_format: The output format for the report, "json", "csv", or "df", default to "json".
        :param csv_file: Filepath to save CSV output if `output_format` is "csv", must be provided.

        :returns:
            JSON or DataFrame with aggregated scores, in case the output is set to a CSV file, a message confirming the
            successful write or an error message.
        """
        results = {k: v["score"] for k, v in self.results.items()}

View on GitHub (pinned to e318778c9b)

Solutions

Pass csv_file='/path/to/report.csv' when using output_format='csv'.
Default to output_format='json' or 'df' if no file output is needed.
Wrap the call and validate csv_file is set before invoking.

Example fix

// before
run.aggregated_report(output_format='csv')
// after
run.aggregated_report(output_format='csv', csv_file='report.csv')

Defensive patterns

Strategy: validation

Validate before calling

if output_format == 'csv' and not csv_file:
    raise ValueError('csv_file path required for CSV output')

Type guard

null

Try / catch

try:
    report = run.aggregated_report(output_format='csv', csv_file=csv_file)
except ValueError as e:
    if "csv_file" in str(e):
        report = run.aggregated_report(output_format='json')
    else:
        raise

Prevention

Always supply csv_file when output_format='csv'
Resolve the output path from config with a non-empty default
Add a small wrapper that sets a default filename per report type

When it happens

Trigger: Calling run.aggregated_report(output_format='csv') (or detailed_report / comparative_detailed_report) without passing csv_file='path/to/file.csv'.

Common situations: Switching output_format from 'json'/'df' to 'csv' in existing code and forgetting the extra parameter; scripting report generation where the path variable was empty or None.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/b245c6e32204110e. Report an issue: GitHub.