{"record":{"id":"6e89e4b88b5718d3","repo":"deepset-ai/haystack","slug":"the-matched-leaf-documents-do-not-have-the-require-6e89e4","errorCode":null,"errorMessage":"The matched leaf documents do not have the required meta field '__level'","messagePattern":"The matched leaf documents do not have the required meta field '__level'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"haystack/components/retrievers/auto_merging_retriever.py","lineNumber":108,"sourceCode":"    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)\n        \"\"\"\n\n        AutoMergingRetriever._check_valid_documents(documents)","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/retrievers/auto_merging_retriever.py#L90-L126","documentation":"Same validation as '__parent_id': each leaf document must carry a '__level' meta entry recording its position in the document hierarchy. If any matched leaf lacks '__level', _check_valid_documents raises this ValueError before merging.","triggerScenarios":"run() receives leaf documents whose meta lacks '__level' — e.g. hand-built Documents, partially migrated stores, or meta keys stripped during serialization.","commonSituations":"Custom ingestion pipelines that copy docs but drop dunder meta keys; mixing documents from old/new indexing code paths.","solutions":["Use HierarchicalDocumentSplitter output so leaves include '__level'","Add '__level' to each leaf's meta before run()","Re-index documents missing hierarchy meta"],"exampleFix":"// before\ndoc.meta = {\"__parent_id\": pid, \"__block_size\": 5}\n// after\ndoc.meta = {\"__parent_id\": pid, \"__level\": 2, \"__block_size\": 5}","handlingStrategy":"validation","validationCode":"missing = [d.id for d in docs if not d.meta.get(\"__level\")]\nif missing:\n    raise ValueError(f\"Leaves missing '__level': {missing}\")","typeGuard":"def has_level(doc: Document) -> bool:\n    return bool(doc.meta.get(\"__level\"))","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":["Preserve full splitter meta through serialization","Validate '__parent_id', '__level', '__block_size' together","Re-index after haystack upgrades that change internal meta keys"],"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"}