deepset-ai/haystack · error · ValueError

Invalid value for word_count_threshold: {word_count_threshol

Error message

Invalid value for word_count_threshold: {word_count_threshold}. word_count_threshold must be > 0.

What it means

LostInTheMiddleRanker's __init__ rejects a word_count_threshold that is an int <= 0. The ranker uses this value as the maximum total number of words across all selected documents, so a zero or negative value is meaningless and would make document selection impossible. The library raises ValueError eagerly at construction time to fail fast.

Source

Thrown at haystack/components/rankers/lost_in_the_middle.py:53

    for doc in result["documents"]:
        print(doc.content)
    ```
    """

    def __init__(self, word_count_threshold: int | None = None, top_k: int | None = None) -> None:
        """
        Initialize the LostInTheMiddleRanker.

        If 'word_count_threshold' is specified, this ranker includes all documents up until the point where adding
        another document would exceed the 'word_count_threshold'. The last document that causes the threshold to
        be breached will be included in the resulting list of documents, but all subsequent documents will be
        discarded.

        :param word_count_threshold: The maximum total number of words across all documents selected by the ranker.
        :param top_k: The maximum number of documents to return.
        """
        if isinstance(word_count_threshold, int) and word_count_threshold <= 0:
            raise ValueError(
                f"Invalid value for word_count_threshold: {word_count_threshold}. word_count_threshold must be > 0."
            )
        if isinstance(top_k, int) and top_k <= 0:
            raise ValueError(f"top_k must be > 0, but got {top_k}")

        self.word_count_threshold = word_count_threshold
        self.top_k = top_k

    @component.output_types(documents=list[Document])
    def run(
        self, documents: list[Document], top_k: int | None = None, word_count_threshold: int | None = None
    ) -> dict[str, list[Document]]:
        """
        Reranks documents based on the "lost in the middle" order.

        Before ranking, documents are deduplicated by their id, retaining only the document with the highest score
        if a score is present.

View on GitHub (pinned to e318778c9b)

Solutions

1. Pass a positive integer, e.g. LostInTheMiddleRanker(word_count_threshold=1024).
2. If the value comes from config, validate/coerce it before construction and fall back to a sensible default.
3. If you intended no word limit, omit the parameter and use top_k-based selection instead of passing 0.

Example fix

// before
ranker = LostInTheMiddleRanker(word_count_threshold=0)
// after
ranker = LostInTheMiddleRanker(word_count_threshold=1024)

def ensure_valid_word_count_threshold(v):
    if isinstance(v, int) and v <= 0:
        raise ValueError(f"word_count_threshold must be > 0, got {v}")
    return v
# call before: ensure_valid_word_count_threshold(cfg["word_count_threshold"])

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

try:
    ranker = LostInTheMiddleRanker(word_count_threshold=cfg_threshold)
except ValueError as e:
    logger.warning("Falling back to default word_count_threshold: %s", e)
    ranker = LostInTheMiddleRanker()

When it happens

Trigger: Calling LostInTheMiddleRanker(word_count_threshold=0) or any negative integer; the check only fires when the value is an int instance, so None, floats, or non-numeric values pass validation.

Common situations: Constructing the ranker from config files where a placeholder 0 was left; computing the threshold dynamically (e.g. len(docs) on an empty list or a subtraction going negative); YAML/JSON deserialization filling in 0 for missing keys.

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

• top_k must be > 0, but got {top_k}
• 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.

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