deepset-ai/haystack · error · ValueError

row_split_threshold must be greater than 0

Error message

row_split_threshold must be greater than 0

What it means

CSVDocumentSplitter requires row_split_threshold to be None or >= 1 when used; values less than 1 (0 or negative) are rejected in __init__ with ValueError. The threshold counts consecutive empty rows that trigger a split.

Source

Thrown at haystack/components/preprocessors/csv_document_splitter.py:61

        :param column_split_threshold: The minimum number of consecutive empty columns required to trigger a split.
        :param read_csv_kwargs: Additional keyword arguments to pass to `pandas.read_csv`.
            By default, the component with options:
            - `header=None`
            - `skip_blank_lines=False` to preserve blank lines
            - `dtype=object` to prevent type inference (e.g., converting numbers to floats).
            See https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html for more information.
        :param split_mode:
            If `threshold`, the component will split the document based on the number of
            consecutive empty rows or columns that exceed the `row_split_threshold` or `column_split_threshold`.
            If `row-wise`, the component will split each row into a separate sub-table.
        """
        pandas_import.check()
        if split_mode not in get_args(SplitMode):
            raise ValueError(
                f"Split mode '{split_mode}' not recognized. Choose one among: {', '.join(get_args(SplitMode))}."
            )
        if row_split_threshold is not None and row_split_threshold < 1:
            raise ValueError("row_split_threshold must be greater than 0")

        if column_split_threshold is not None and column_split_threshold < 1:
            raise ValueError("column_split_threshold must be greater than 0")

        if row_split_threshold is None and column_split_threshold is None:
            raise ValueError("At least one of row_split_threshold or column_split_threshold must be specified.")

        self.row_split_threshold = row_split_threshold
        self.column_split_threshold = column_split_threshold
        self.read_csv_kwargs = read_csv_kwargs or {}
        self.split_mode = split_mode

    @component.output_types(documents=list[Document])
    def run(self, documents: list[Document]) -> dict[str, list[Document]]:
        """
        Processes and splits a list of CSV documents into multiple sub-tables.

        **Splitting Process:**

View on GitHub (pinned to e318778c9b)

Solutions

1. Set row_split_threshold to a positive integer (>= 1) or None to disable it.
2. Pass None instead of 0 when the threshold should be unused.
3. Ensure at least one of row/column thresholds is specified, since both None raises a separate error.

Example fix

// before
CSVDocumentSplitter(split_mode="threshold", row_split_threshold=0)
// after
CSVDocumentSplitter(split_mode="threshold", row_split_threshold=None, column_split_threshold=2)

if row_split_threshold is not None and row_split_threshold < 1:
    raise ValueError("row_split_threshold must be >= 1 or None")
splitter = CSVDocumentSplitter(row_split_threshold=row_split_threshold, column_split_threshold=col_t)

def is_valid_threshold(v: int | None) -> bool:
    return v is None or (isinstance(v, int) and v >= 1)

try:
    splitter = CSVDocumentSplitter(split_mode="threshold", row_split_threshold=t)
except ValueError as e:
    logger.warning("invalid row_split_threshold %r: %s", t, e)
    splitter = CSVDocumentSplitter(split_mode="threshold", row_split_threshold=None, column_split_threshold=2)

When it happens

Trigger: CSVDocumentSplitter(row_split_threshold=0) or a negative value; typically when column_split_threshold is also set (threshold mode) or alone.

Common situations: Setting 0 to mean 'disable' instead of passing None; config defaults of 0; confusing 'disable' semantics with the None sentinel.

Understand the failure class

Background: "must be positive", "Invalid value": how libraries reject invalid parameter values (ValueError, ArgumentError, INVALID_PARAMETER_VALUE) — this error's family across 28 libraries.

Related errors

• 'response_fn' must return an assistant ChatMessage, got '{re
• Cannot stream multiple responses, please set n=1.
• A `ChatMessage` must contain at least one `TextContent`, `To
• top_k must be greater than 0.
• top_k must not be negative.

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