deepset-ai/haystack · error · ValueError

min_effective_lines must be at least 1.

Error message

min_effective_lines must be at least 1.

What it means

PythonCodeSplitter's __init__ validates min_effective_lines: the minimum number of code lines per chunk must be at least 1. Zero or negative values are meaningless for chunking, so ValueError is raised.

Source

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

            ``ceil(len(source) / expected_chars_per_line)``; long lines count as more than one.
        :param oversized_factor: A function whose effective length exceeds
            ``oversized_factor * max_effective_lines`` triggers the line-based secondary
            split with overlap.
        :param strip_docstrings: If ``True``, function/method/class docstrings are moved
            from the chunk content into ``meta["docstrings"]`` (source order). The
            module-level docstring is kept in place since it is itself a top-level unit.
        :param preserve_class_definition: If ``True`` (default), chunks that contain class
            members but not the class header are prefixed with the bare class signature
            (decorators plus the ``class Foo(...):`` lines) in source order.
        :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

View on GitHub (pinned to e318778c9b)

Solutions

1. Pass min_effective_lines >= 1, e.g. min_effective_lines=5.
2. Omit the parameter to use the documented default.
3. Clamp dynamic values: min_effective_lines=max(1, computed_value).
4. Fix env/config parsing to use a sane default instead of 0.

Example fix

// before
PythonCodeSplitter(min_effective_lines=0)
// after
PythonCodeSplitter(min_effective_lines=5)

min_effective_lines = max(1, int(min_effective_lines))
splitter = PythonCodeSplitter(min_effective_lines=min_effective_lines)

def is_positive_int(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and v >= 1

try:
    splitter = PythonCodeSplitter(min_effective_lines=min_lines)
except ValueError as e:
    logging.warning("Invalid min_effective_lines (%s), using default", e)
    splitter = PythonCodeSplitter()

When it happens

Trigger: Calling PythonCodeSplitter(min_effective_lines=0) or a negative value, often when computing the value dynamically (e.g. multiplying by a zero factor) or copying a config where the field defaulted to 0.

Common situations: Zero-initialized config variables, env vars parsed as ints defaulting to 0, or misunderstanding that 0 means 'no minimum' (it is rejected instead).

Related errors

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

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