run-llama/llama_index · error · ValueError

Previous object must be a single RelatedNodeInfo object

Error message

Previous object must be a single RelatedNodeInfo object

What it means

TextNode.prev_node reads relationships[NodeRelationship.PREVIOUS] and requires a RelatedNodeInfo instance specifically. Unlike SOURCE (which rejects any list), PREVIOUS must be exactly that type — a dict, a list, or any other shape raises ValueError.

Source

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

        """
        if NodeRelationship.SOURCE not in self.relationships:
            return None

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

    @property
    def prev_node(self) -> Optional[RelatedNodeInfo]:
        """Prev node."""
        if NodeRelationship.PREVIOUS not in self.relationships:
            return None

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

    @property
    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

View on GitHub (pinned to afd0fef371)

Solutions

1. Wrap the value in RelatedNodeInfo: RelatedNodeInfo(**your_dict)
2. Rebuild nodes through TextNode/Document constructors or node parsers, which produce well-typed relationships
3. Validate relationships with a check that PREVIOUS is isinstance(x, RelatedNodeInfo) before storing to a docstore

Example fix

# before
node.relationships[NodeRelationship.PREVIOUS] = {"node_id": prev_id}

# after
from llama_index.core.schema import RelatedNodeInfo
node.relationships[NodeRelationship.PREVIOUS] = RelatedNodeInfo(node_id=prev_id)

from llama_index.core.schema import RelatedNodeInfo, NodeRelationship
rel = node.relationships.get(NodeRelationship.PREVIOUS)
if rel is not None and not isinstance(rel, RelatedNodeInfo):
    node.relationships[NodeRelationship.PREVIOUS] = RelatedNodeInfo.model_validate(rel)

def has_valid_prev(node) -> bool:
    rel = node.relationships.get(NodeRelationship.PREVIOUS)
    return rel is None or type(rel).__name__ == "RelatedNodeInfo"

When it happens

Trigger: Assigning node.relationships[NodeRelationship.PREVIOUS] = {"node_id": ...} (a plain dict) or a list instead of a RelatedNodeInfo instance, then reading .prev_node.

Common situations: Building nodes from raw dicts/deserialized JSON where relationships were reconstructed as plain dictionaries; copy-pasting the CHILD list pattern into PREVIOUS.

Related errors

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

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