{"record":{"id":"8cefed73c525fc65","repo":"deepset-ai/haystack","slug":"the-matched-leaf-documents-do-not-have-the-require","errorCode":null,"errorMessage":"The matched leaf documents do not have the required meta field '__parent_id'","messagePattern":"The matched leaf documents do not have the required meta field '__parent_id'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"haystack/components/retrievers/auto_merging_retriever.py","lineNumber":105,"sourceCode":"        return default_to_dict(self, document_store=self.document_store, threshold=self.threshold)\n\n    @classmethod\n    def from_dict(cls, data: dict[str, Any]) -> \"AutoMergingRetriever\":\n        \"\"\"\n        Deserializes the component from a dictionary.\n\n        :param data:\n            Dictionary with serialized data.\n        :returns:\n            An instance of the component.\n        \"\"\"\n        return default_from_dict(cls, data)\n\n    @staticmethod\n    def _check_valid_documents(matched_leaf_documents: list[Document]) -> None:\n        # check if the matched leaf documents have the required meta fields\n        if not all(doc.meta.get(\"__parent_id\") for doc in matched_leaf_documents):\n            raise ValueError(\"The matched leaf documents do not have the required meta field '__parent_id'\")\n\n        if not all(doc.meta.get(\"__level\") for doc in matched_leaf_documents):\n            raise ValueError(\"The matched leaf documents do not have the required meta field '__level'\")\n\n        if not all(doc.meta.get(\"__block_size\") for doc in matched_leaf_documents):\n            raise ValueError(\"The matched leaf documents do not have the required meta field '__block_size'\")\n\n    @component.output_types(documents=list[Document])\n    def run(self, documents: list[Document]) -> dict[str, list[Document]]:\n        \"\"\"\n        Run the AutoMergingRetriever.\n\n        Recursively groups documents by their parents and merges them if they meet the threshold,\n        continuing up the hierarchy until no more merges are possible.\n\n        :param documents: List of leaf documents that were matched by a retriever\n        :returns:\n            List of documents (could be a mix of different hierarchy levels)","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/retrievers/auto_merging_retriever.py#L87-L123","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Index documents produced by HierarchicalDocumentSplitter so leaves carry '__parent_id'","Inspect doc.meta keys and ensure '__parent_id' is set on every leaf document before run()","Re-index the document store if it was built with an older splitter version"],"exampleFix":"// before\nleaf = Document(content=\"text\")\nretriever.run(documents=[leaf])\n// after\nleaf = Document(content=\"text\", meta={\"__parent_id\": parent.id, \"__level\": 1, \"__block_size\": 5})\nretriever.run(documents=[leaf])","handlingStrategy":"validation","validationCode":"missing = [d.id for d in docs if not d.meta.get(\"__parent_id\")]\nif missing:\n    raise ValueError(f\"Leaves missing '__parent_id': {missing}\")","typeGuard":"def has_parent_id(doc: Document) -> bool:\n    return bool(doc.meta.get(\"__parent_id\"))","tryCatchPattern":"try:\n    result = retriever.run(documents=docs)\nexcept ValueError as e:\n    logger.error(\"Leaf docs invalid for auto-merging: %s\", e)\n    result = {\"documents\": docs}  # fallback: return unmerged","preventionTips":["Always index via HierarchicalDocumentSplitter","Never strip dunder-prefixed meta keys in preprocessing","Check meta keys before writing to the store"],"tags":["retriever","meta-field","documents","validation"],"backgroundTag":"missing-metadata-field","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}