deepset-ai/haystack · error · ValueError

secondary_split_overlap must be non-negative.

Error message

secondary_split_overlap must be non-negative.

What it means

PythonCodeSplitter's __init__ validates all constructor parameters, and secondary_split_overlap (the overlap used when chunking oversized chunks via the secondary splitter) must be >= 0. A negative value would make sliding-window chunking nonsensical, so the splitter refuses to initialize. This is a fail-fast configuration check.

Source

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

        :param secondary_split_overlap: Line overlap for the secondary splitter; only used
            in the oversized fallback. The primary AST split never adds overlap.
        :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))

View on GitHub (pinned to e318778c9b)

Solutions

1. Set secondary_split_overlap to 0 or a positive integer smaller than secondary_split_length.
2. If the value is computed, clamp it: max(0, computed_overlap).
3. If no secondary overlap is needed, omit the parameter to use the default.

Example fix

// before
splitter = PythonCodeSplitter(secondary_split_overlap=-5)
// after
splitter = PythonCodeSplitter(secondary_split_overlap=5)

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

def is_valid_overlap(v) -> bool:
    return isinstance(v, int) and v >= 0

try:
    splitter = PythonCodeSplitter(secondary_split_overlap=overlap)
except ValueError as e:
    logger.error('Invalid splitter config: %s', e)
    splitter = PythonCodeSplitter()  # defaults

When it happens

Trigger: Constructing PythonCodeSplitter(secondary_split_overlap=-N) for any negative integer, e.g. copying a config where overlap was computed dynamically and went negative, or sign typos like secondary_split_overlap=-20.

Common situations: Loading splitter settings from YAML/env/config files where the value is parsed or computed programmatically; hand-editing parameters and accidentally negating the value.

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/ce3341fa61824a81. Report an issue: GitHub.