deepset-ai/haystack · error · ValueError

The matched leaf documents do not have the required meta fie

Error message

The matched leaf documents do not have the required meta field '__parent_id'

What it means

AutoMergingRetriever reconstructs parent documents from leaf documents that carry hierarchy metadata. Every matched leaf must contain '__parent_id' in its meta; _check_valid_documents raises this ValueError if any document is missing it.

Source

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

        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.

        :param data:
            Dictionary with serialized data.
        :returns:
            An instance of the component.
        """
        return default_from_dict(cls, data)

    @staticmethod
    def _check_valid_documents(matched_leaf_documents: list[Document]) -> None:
        # check if the matched leaf documents have the required meta fields
        if not all(doc.meta.get("__parent_id") for doc in matched_leaf_documents):
            raise ValueError("The matched leaf documents do not have the required meta field '__parent_id'")

        if not all(doc.meta.get("__level") for doc in matched_leaf_documents):
            raise ValueError("The matched leaf documents do not have the required meta field '__level'")

        if not all(doc.meta.get("__block_size") for doc in matched_leaf_documents):
            raise ValueError("The matched leaf documents do not have the required meta field '__block_size'")

    @component.output_types(documents=list[Document])
    def run(self, documents: list[Document]) -> dict[str, list[Document]]:
        """
        Run the AutoMergingRetriever.

        Recursively groups documents by their parents and merges them if they meet the threshold,
        continuing up the hierarchy until no more merges are possible.

        :param documents: List of leaf documents that were matched by a retriever
        :returns:
            List of documents (could be a mix of different hierarchy levels)

View on GitHub (pinned to e318778c9b)

Solutions

1. Index documents produced by HierarchicalDocumentSplitter so leaves carry '__parent_id'
2. Inspect doc.meta keys and ensure '__parent_id' is set on every leaf document before run()
3. Re-index the document store if it was built with an older splitter version

Example fix

// before
leaf = Document(content="text")
retriever.run(documents=[leaf])
// after
leaf = Document(content="text", meta={"__parent_id": parent.id, "__level": 1, "__block_size": 5})
retriever.run(documents=[leaf])

missing = [d.id for d in docs if not d.meta.get("__parent_id")]
if missing:
    raise ValueError(f"Leaves missing '__parent_id': {missing}")

def has_parent_id(doc: Document) -> bool:
    return bool(doc.meta.get("__parent_id"))

try:
    result = retriever.run(documents=docs)
except ValueError as e:
    logger.error("Leaf docs invalid for auto-merging: %s", e)
    result = {"documents": docs}  # fallback: return unmerged

When it happens

Trigger: Calling run() with leaf Documents that were not indexed by HierarchicalDocumentSplitter / written with the '__parent_id' meta key, or whose meta was stripped/renamed before retrieval.

Common situations: Feeding manually created Documents into the retriever, writing documents to the store without hierarchy meta, or upgrading haystack so older indexed docs lack the internal meta keys.

Related errors

• The matched leaf documents do not have the required meta fie
• The matched leaf documents do not have the required meta fie
• top_k must be > 0, but got {top_k}
• Parameter <weight> must be in range [0,1] but is currently s
• The threshold parameter must be between 0 and 1.

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