deepset-ai/haystack · error · ValueError

Split mode '{split_mode}' not recognized. Choose one among:

Error message

Split mode '{split_mode}' not recognized. Choose one among: {', '.join(get_args(SplitMode))}.

What it means

CSVDocumentSplitter.__init__ validates split_mode against the SplitMode Literal ('row-wise', 'column-wise', 'threshold'). An unrecognized string raises ValueError listing the valid options.

Source

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

        """
        Initializes the CSVDocumentSplitter component.

        :param row_split_threshold: The minimum number of consecutive empty rows required to trigger a split.
        :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]]:

View on GitHub (pinned to e318778c9b)

Solutions

1. Use one of the exact allowed strings: 'row-wise', 'column-wise', or 'threshold'.
2. Fix casing — comparison is case-sensitive lowercase.
3. Check get_args(SplitMode) from haystack.components.preprocessors.csv_document_splitter for the authoritative list.

Example fix

// before
CSVDocumentSplitter(split_mode="rows")
// after
CSVDocumentSplitter(split_mode="row-wise")

from typing import get_args
from haystack.components.preprocessors.csv_document_splitter import SplitMode
VALID = get_args(SplitMode)
assert split_mode in VALID, f"split_mode must be one of {VALID}, got {split_mode!r}"

def is_split_mode(s: str) -> bool:
    from typing import get_args
    from haystack.components.preprocessors.csv_document_splitter import SplitMode
    return s in get_args(SplitMode)

try:
    splitter = CSVDocumentSplitter(split_mode=mode)
except ValueError as e:
    logger.error("bad split_mode %r: %s", mode, e)
    splitter = CSVDocumentSplitter(split_mode="row-wise", row_split_threshold=2)

When it happens

Trigger: CSVDocumentSplitter(split_mode='rows'), split_mode='ROW-WISE' (wrong casing), or any string outside get_args(SplitMode).

Common situations: Typos or shorthand; wrong casing; assuming modes from other splitters (e.g. sentence/page splitters) apply here.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown join mode '{string}'. Supported modes in DocumentJoi
• The following tool names are not valid: {invalid_tool_names}
• user_prompt must define exactly one message block, found {le
• system_prompt must define exactly one message block, found {
• Number of replies ({len(replies)}), and metadata ({len(meta)

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