deepset-ai/haystack · error · ValueError

oversized_factor must be at least 1.

Error message

oversized_factor must be at least 1.

What it means

PythonCodeSplitter's __init__ requires oversized_factor >= 1. This factor decides when a chunk counts as oversized (relative to the target size); a value below 1 would mark normal chunks oversized, so ValueError is raised.

Source

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

            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
        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

View on GitHub (pinned to e318778c9b)

Solutions

1. Use a factor >= 1, e.g. oversized_factor=1.5 (chunks 50% over target are oversized).
2. Omit the parameter to use the default.
3. Convert percentage configs correctly: factor = 1 + pct/100.
4. Validate the config value before construction: assert oversized_factor >= 1.

Example fix

// before
PythonCodeSplitter(oversized_factor=0.5)  # meant 50%
// after
PythonCodeSplitter(oversized_factor=1.5)  # 50% over target = oversized

if oversized_factor < 1:
    oversized_factor = 1 + oversized_factor  # interpret 0.5 as 50% over
code_splitter = PythonCodeSplitter(oversized_factor=max(1.0, oversized_factor))

def is_valid_oversized_factor(v) -> bool:
    return isinstance(v, (int, float)) and v >= 1

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

When it happens

Trigger: Calling PythonCodeSplitter(oversized_factor=0.5) or 0, e.g. from a fractional multiplier intended to shrink chunks or a config value expressed as a percentage (50 instead of 1.5... but <1 percentages like 0.5 fail).

Common situations: Confusing the factor with a percentage (0.5 for 50%), setting it to 1.0-expecting shrink behavior, or copying defaults from a different splitter whose parameter semantics differ.

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.
• secondary_split_overlap must be non-negative.

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