deepset-ai/haystack · error · ValueError

Expected 1 parent document with id {parent_id}, found {len(p

Error message

Expected 1 parent document with id {parent_id}, found {len(parent_docs)}

What it means

When merging leaf documents, the retriever looks up each parent document by exact id via document_store.filter_documents. It requires exactly one match; zero matches (missing parent) or multiple matches (store inconsistency) raise this ValueError.

Source

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

    @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)
        """

        AutoMergingRetriever._check_valid_documents(documents)

        def _get_parent_doc(parent_id: str) -> Document:
            parent_docs = self.document_store.filter_documents({"field": "id", "operator": "==", "value": parent_id})
            if len(parent_docs) != 1:
                raise ValueError(f"Expected 1 parent document with id {parent_id}, found {len(parent_docs)}")

            parent_doc = parent_docs[0]
            if not parent_doc.meta.get("__children_ids"):
                raise ValueError(f"Parent document with id {parent_id} does not have any children.")

            return parent_doc

        def _try_merge_level(docs_to_merge: list[Document], docs_to_return: list[Document]) -> list[Document]:
            parent_doc_id_to_child_docs: dict[str, list[Document]] = defaultdict(list)  # to group documents by parent

            for doc in docs_to_merge:
                if doc.meta.get("__parent_id"):  # only docs that have parents
                    parent_doc_id_to_child_docs[doc.meta["__parent_id"]].append(doc)
                else:
                    docs_to_return.append(doc)  # keep docs that have no parents

            # Process each parent group
            merged_docs = []

View on GitHub (pinned to e318778c9b)

Solutions

1. Ensure all parent documents referenced by '__parent_id' exist in the document_store
2. Re-run the hierarchical indexing pipeline to restore missing parents
3. Check for duplicate document ids in the store

Example fix

// before
store.delete_documents([parent_doc])  # children now orphaned
retriever.run(documents=leaves)
// after
# keep parents in the store when children remain
retriever.run(documents=leaves)

for doc in leaves:
    pid = doc.meta.get("__parent_id")
    found = store.filter_documents({"field": "id", "operator": "==", "value": pid})
    if len(found) != 1:
        raise ValueError(f"Parent {pid} missing or duplicated in store")

try:
    result = retriever.run(documents=leaves)
except ValueError as e:
    logger.warning("Parent lookup failed: %s — returning leaf documents", e)
    result = {"documents": leaves}

When it happens

Trigger: run()/sync merging where a child's '__parent_id' has no corresponding document in the store, or the store contains duplicate ids for the parent.

Common situations: Deleting parent documents while keeping leaves, partial re-indexing, or a custom document store whose filter returns unexpected results.

Related errors

• Parent document with id {parent_id} does not have any childr
• document_store must be an instance of InMemoryDocumentStore
• Document store {type(self.document_store).__name__} does not
• The threshold parameter must be between 0 and 1.
• The matched leaf documents do not have the required meta fie

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