run-llama/llama_index · error · ValueError

Parent object must be a single RelatedNodeInfo object

Error message

Parent object must be a single RelatedNodeInfo object

What it means

TextNode.parent_node reads relationships[NodeRelationship.PARENT] and requires a single RelatedNodeInfo instance. PARENT points from a child chunk to its parent node in hierarchies (e.g. auto-merging retriever indexes), so a list or dict value is rejected.

Source

Thrown at llama-index-core/llama_index/core/schema.py:436

    def next_node(self) -> Optional[RelatedNodeInfo]:
        """Next node."""
        if NodeRelationship.NEXT not in self.relationships:
            return None

        relation = self.relationships[NodeRelationship.NEXT]
        if not isinstance(relation, RelatedNodeInfo):
            raise ValueError("Next object must be a single RelatedNodeInfo object")
        return relation

    @property
    def parent_node(self) -> Optional[RelatedNodeInfo]:
        """Parent node."""
        if NodeRelationship.PARENT not in self.relationships:
            return None

        relation = self.relationships[NodeRelationship.PARENT]
        if not isinstance(relation, RelatedNodeInfo):
            raise ValueError("Parent object must be a single RelatedNodeInfo object")
        return relation

    @property
    def child_nodes(self) -> Optional[List[RelatedNodeInfo]]:
        """Child nodes."""
        if NodeRelationship.CHILD not in self.relationships:
            return None

        relation = self.relationships[NodeRelationship.CHILD]
        if not isinstance(relation, list):
            raise ValueError("Child objects must be a list of RelatedNodeInfo objects.")
        return relation

    @property
    def ref_doc_id(self) -> Optional[str]:  # pragma: no cover
        """Deprecated: Get ref doc id."""
        source_node = self.source_node
        if source_node is None:

View on GitHub (pinned to afd0fef371)

Solutions

1. Store a single RelatedNodeInfo for PARENT
2. Use HierarchicalNodeParser.get_leaf_nodes/get_root_nodes workflows which set PARENT correctly
3. Validate the relationship type before writing nodes to storage

Example fix

# before
node.relationships[NodeRelationship.PARENT] = [RelatedNodeInfo(node_id=parent_id)]

# after
node.relationships[NodeRelationship.PARENT] = RelatedNodeInfo(node_id=parent_id)

rel = node.relationships.get(NodeRelationship.PARENT)
if rel is not None and not isinstance(rel, RelatedNodeInfo):
    node.relationships[NodeRelationship.PARENT] = RelatedNodeInfo.model_validate(rel)

def has_valid_parent(node) -> bool:
    rel = node.relationships.get(NodeRelationship.PARENT)
    return rel is None or isinstance(rel, RelatedNodeInfo)

When it happens

Trigger: Assigning relationships[NodeRelationship.PARENT] a list or plain dict instead of RelatedNodeInfo, then calling .parent_node — typically in custom hierarchical ingestion or when hand-editing docstore records.

Common situations: Custom parent-child builders that mirror the CHILD (list) shape for PARENT; docstore records migrated or hand-edited so PARENT became a list.

Related errors

• Child objects must be a list of RelatedNodeInfo objects.
• Source object must be a single RelatedNodeInfo object
• Previous object must be a single RelatedNodeInfo object
• Next object must be a single RelatedNodeInfo object
• embedding not set.

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/52751914fb410f4b. Report an issue: GitHub.