deepset-ai/haystack · error · ValueError

secondary_split_length must be at least 1.

Error message

secondary_split_length must be at least 1.

What it means

PythonCodeSplitter.__init__ requires secondary_split_length, when provided, to be at least 1 character. A length of 0 or negative cannot produce any chunks, so initialization fails fast with this ValueError.

Source

Thrown at haystack/components/preprocessors/python_code_splitter.py:136

        :param secondary_split_length: Lines per chunk for the secondary splitter.
            Defaults to ``max_effective_lines`` when ``None``.
        :raises ValueError: If any parameter is invalid (negative, zero where positive is
            required, or ``min_effective_lines > max_effective_lines``).
        """
        if min_effective_lines < 1:
            raise ValueError("min_effective_lines must be at least 1.")
        if max_effective_lines < 1:
            raise ValueError("max_effective_lines must be at least 1.")
        if min_effective_lines > max_effective_lines:
            raise ValueError("min_effective_lines must not be greater than max_effective_lines.")
        if expected_chars_per_line < 1:
            raise ValueError("expected_chars_per_line must be at least 1.")
        if oversized_factor < 1:
            raise ValueError("oversized_factor must be at least 1.")
        if secondary_split_overlap < 0:
            raise ValueError("secondary_split_overlap must be non-negative.")
        if secondary_split_length is not None and secondary_split_length < 1:
            raise ValueError("secondary_split_length must be at least 1.")

        self.min_effective_lines = min_effective_lines
        self.max_effective_lines = max_effective_lines
        self.expected_chars_per_line = expected_chars_per_line
        self.oversized_factor = oversized_factor
        self.strip_docstrings = strip_docstrings
        self.preserve_class_definition = preserve_class_definition
        self.secondary_split_overlap = secondary_split_overlap
        self.secondary_split_length = secondary_split_length

    def _effective_lines(self, text: str) -> int:
        """Return the number of *effective lines* for ``text`` (see class docstring)."""
        if not text:
            return 0
        return max(1, math.ceil(len(text) / self.expected_chars_per_line))

    def _is_oversized(self, unit: "_CodeUnit") -> bool:
        """Return ``True`` if ``unit`` should trigger the secondary line-based split."""

View on GitHub (pinned to e318778c9b)

Solutions

1. Set secondary_split_length to a positive integer (e.g. 500-1000).
2. If the value is dynamic, validate/clamp before constructing: max(1, n).
3. Pass None instead of 0 to fall back to the default secondary length.

Example fix

// before
splitter = PythonCodeSplitter(secondary_split_length=0)
// after
splitter = PythonCodeSplitter(secondary_split_length=512)

if secondary_split_length is not None and secondary_split_length < 1:
    raise ValueError(f'secondary_split_length must be >= 1, got {secondary_split_length}')

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

try:
    splitter = PythonCodeSplitter(secondary_split_length=cfg.get('secondary_split_length'))
except ValueError as e:
    logger.error('Invalid secondary_split_length: %s', e)
    splitter = PythonCodeSplitter()

When it happens

Trigger: PythonCodeSplitter(secondary_split_length=0), a negative value, or passing None-derived values into arithmetic that yields < 1.

Common situations: Config-driven pipelines where secondary_split_length comes from user input or a computed expression that resolves to 0; misunderstanding that None means 'use default' while 0 means 'invalid'.

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

• header_split_levels must be a non-empty list.
• min_effective_lines must be at least 1.
• max_effective_lines must be at least 1.
• expected_chars_per_line must be at least 1.
• oversized_factor must be at least 1.

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