deepset-ai/haystack · error · ValueError

The threshold parameter must be between 0 and 1.

Error message

The threshold parameter must be between 0 and 1.

What it means

AutoMergingRetriever uses `threshold` as the fraction of leaf documents under a parent that must be matched before the parent document replaces them. Since it is a proportion, it is strictly validated to lie between 0 and 1 (exclusive) in __init__.

Source

Thrown at haystack/components/retrievers/auto_merging_retriever.py:75

    retrieved_docs = retriever.run(leaf_docs[4:6])
    print(retrieved_docs["documents"])
    # [Document(id=538..),
    # content: 'warm glow over the trees. Birds began to sing.',
    # meta: {'block_size': 10, 'parent_id': '835..', 'children_ids': ['c17...', '3ff...', '352...'], 'level': 1, 'source_id': '835...',
    # 'page_number': 1, 'split_id': 1, 'split_idx_start': 45})]}
    ```
    """  # noqa: E501

    def __init__(self, document_store: DocumentStore, threshold: float = 0.5) -> None:
        """
        Initialize the AutoMergingRetriever.

        :param document_store: DocumentStore from which to retrieve the parent documents
        :param threshold: Threshold to decide whether the parent instead of the individual documents is returned
        """

        if not 0 < threshold < 1:
            raise ValueError("The threshold parameter must be between 0 and 1.")

        self.document_store = document_store
        self.threshold = threshold

    def to_dict(self) -> dict[str, Any]:
        """
        Serializes the component to a dictionary.

        :returns:
            Dictionary with serialized data.
        """
        return default_to_dict(self, document_store=self.document_store, threshold=self.threshold)

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> "AutoMergingRetriever":
        """
        Deserializes the component from a dictionary.

View on GitHub (pinned to e318778c9b)

Solutions

1. Pass a float strictly between 0 and 1, e.g. 0.5
2. Convert percentage configs to fractions (75 -> 0.75)
3. Check pipeline YAML/env for integer threshold values

Example fix

// before
retriever = AutoMergingRetriever(document_store=store, threshold=75)
// after
retriever = AutoMergingRetriever(document_store=store, threshold=0.75)

if not (isinstance(threshold, float) and 0 < threshold < 1):
    raise ValueError(f"threshold must be a float strictly between 0 and 1, got {threshold}")

def is_valid_threshold(t: object) -> bool:
    return isinstance(t, (int, float)) and 0 < t < 1

try:
    retriever = AutoMergingRetriever(document_store=store, threshold=cfg["threshold"])
except ValueError as e:
    logger.error("Bad threshold: %s", e)
    retriever = AutoMergingRetriever(document_store=store, threshold=0.5)

When it happens

Trigger: AutoMergingRetriever(document_store=store, threshold=1) or threshold=0 or threshold=5 or negative values — any value where `not 0 < threshold < 1`.

Common situations: Configuring threshold as a percentage (e.g. 75 instead of 0.75), or off-by-one boundary values 0 and 1 which are rejected.

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 greater than 0.
• The matched leaf documents do not have the required meta fie
• The matched leaf documents do not have the required meta fie
• The matched leaf documents do not have the required meta fie
• `context_window` must be a positive number of tokens, got {c

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