{"record":{"id":"f486d71b208481cd","repo":"run-llama/llama_index","slug":"next-object-must-be-a-single-relatednodeinfo-objec","errorCode":null,"errorMessage":"Next object must be a single RelatedNodeInfo object","messagePattern":"Next object must be a single RelatedNodeInfo object","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/schema.py","lineNumber":425,"sourceCode":"    def prev_node(self) -> Optional[RelatedNodeInfo]:\n        \"\"\"Prev node.\"\"\"\n        if NodeRelationship.PREVIOUS not in self.relationships:\n            return None\n\n        relation = self.relationships[NodeRelationship.PREVIOUS]\n        if not isinstance(relation, RelatedNodeInfo):\n            raise ValueError(\"Previous object must be a single RelatedNodeInfo object\")\n        return relation\n\n    @property\n    def next_node(self) -> Optional[RelatedNodeInfo]:\n        \"\"\"Next node.\"\"\"\n        if NodeRelationship.NEXT not in self.relationships:\n            return None\n\n        relation = self.relationships[NodeRelationship.NEXT]\n        if not isinstance(relation, RelatedNodeInfo):\n            raise ValueError(\"Next object must be a single RelatedNodeInfo object\")\n        return relation\n\n    @property\n    def parent_node(self) -> Optional[RelatedNodeInfo]:\n        \"\"\"Parent node.\"\"\"\n        if NodeRelationship.PARENT not in self.relationships:\n            return None\n\n        relation = self.relationships[NodeRelationship.PARENT]\n        if not isinstance(relation, RelatedNodeInfo):\n            raise ValueError(\"Parent object must be a single RelatedNodeInfo object\")\n        return relation\n\n    @property\n    def child_nodes(self) -> Optional[List[RelatedNodeInfo]]:\n        \"\"\"Child nodes.\"\"\"\n        if NodeRelationship.CHILD not in self.relationships:\n            return None","sourceCodeStart":407,"sourceCodeEnd":443,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/schema.py#L407-L443","documentation":"TextNode.next_node reads relationships[NodeRelationship.NEXT] and requires an exact RelatedNodeInfo instance; anything else (dict, list, None-like substitutes) raises ValueError. NEXT is a singular, strictly-typed relationship like PREVIOUS.","triggerScenarios":"Setting relationships[NodeRelationship.NEXT] to a plain dict or a list (e.g. when wiring sentence-window or hierarchical node chains manually), then accessing .next_node.","commonSituations":"Manual construction of ordered node chains instead of using SentenceSplitter/node parsers; deserializing relationship maps from JSON where NEXT became a dict.","solutions":["Use RelatedNodeInfo(node_id=...) for the NEXT relationship","Let core node parsers (SentenceSplitter, HierarchicalNodeParser) build prev/next links for you","If consuming external JSON, coerce relationship dicts via RelatedNodeInfo.model_validate(d)"],"exampleFix":"# before\nnode.relationships[NodeRelationship.NEXT] = {\"node_id\": next_id}\n\n# after\nnode.relationships[NodeRelationship.NEXT] = RelatedNodeInfo(node_id=next_id)","handlingStrategy":"validation","validationCode":"rel = node.relationships.get(NodeRelationship.NEXT)\nif rel is not None and not isinstance(rel, RelatedNodeInfo):\n    node.relationships[NodeRelationship.NEXT] = RelatedNodeInfo.model_validate(rel)","typeGuard":"def has_valid_next(node) -> bool:\n    rel = node.relationships.get(NodeRelationship.NEXT)\n    return rel is None or isinstance(rel, RelatedNodeInfo)","tryCatchPattern":null,"preventionTips":["Type relationship values explicitly at construction time","Validate deserialized relationship maps before docstore writes","Prefer node parsers over manual chain wiring"],"tags":["schema","nodes","relationships","data-validation"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}