{"record":{"id":"445beabf5ba192a3","repo":"deepset-ai/haystack","slug":"the-matched-leaf-documents-do-not-have-the-require-445bea","errorCode":null,"errorMessage":"The matched leaf documents do not have the required meta field '__block_size'","messagePattern":"The matched leaf documents do not have the required meta field '__block_size'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"haystack/components/retrievers/auto_merging_retriever.py","lineNumber":111,"sourceCode":"\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)\n        \"\"\"\n\n        AutoMergingRetriever._check_valid_documents(documents)\n\n        def _get_parent_doc(parent_id: str) -> Document:\n            parent_docs = self.document_store.filter_documents({\"field\": \"id\", \"operator\": \"==\", \"value\": parent_id})","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/retrievers/auto_merging_retriever.py#L93-L129","documentation":"Each leaf document must also store '__block_size' in its meta so the retriever knows how many leaves form one full block for merging. A leaf missing this key triggers this ValueError in _check_valid_documents.","triggerScenarios":"run() with leaf documents whose meta lacks '__block_size' — typically documents not produced by the hierarchical splitting/indexing flow.","commonSituations":"Manually constructed Document objects, stores built by custom scripts, or post-processing that rebuilds meta and omits internal keys.","solutions":["Index with HierarchicalDocumentSplitter so '__block_size' is present","Set '__block_size' explicitly on each leaf's meta before run()","Rebuild the document store with the standard hierarchical indexing pipeline"],"exampleFix":"// before\ndoc.meta = {\"__parent_id\": pid, \"__level\": 1}\n// after\ndoc.meta = {\"__parent_id\": pid, \"__level\": 1, \"__block_size\": 5}","handlingStrategy":"validation","validationCode":"missing = [d.id for d in docs if not d.meta.get(\"__block_size\")]\nif missing:\n    raise ValueError(f\"Leaves missing '__block_size': {missing}\")","typeGuard":"def has_block_size(doc: Document) -> bool:\n    return bool(doc.meta.get(\"__block_size\"))","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}","preventionTips":["Use splitter output end-to-end","Write documents with a single vetted indexing pipeline","Add meta-key assertions in ingestion tests"],"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"}