run-llama/llama_index · error · ValueError

Node must be a TextNode to get text.

Error message

Node must be a TextNode to get text.

What it means

NodeWithScore.text proxies to the underlying node but only when it is a TextNode; ImageNode-without-text variants or other BaseNode subclasses make the property raise ValueError. The wrapper deliberately refuses to guess content extraction for non-text nodes.

Source

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

    @classmethod
    def class_name(cls) -> str:
        return "NodeWithScore"

    ##### pass through methods to BaseNode #####
    @property
    def node_id(self) -> str:
        return self.node.node_id

    @property
    def id_(self) -> str:
        return self.node.id_

    @property
    def text(self) -> str:
        if isinstance(self.node, TextNode):
            return self.node.text
        else:
            raise ValueError("Node must be a TextNode to get text.")

    @property
    def metadata(self) -> Dict[str, Any]:
        return self.node.metadata

    @property
    def embedding(self) -> Optional[List[float]]:
        return self.node.embedding

    def get_text(self) -> str:
        if isinstance(self.node, TextNode):
            return self.node.get_text()
        else:
            raise ValueError("Node must be a TextNode to get text.")

    def get_content(self, metadata_mode: MetadataMode = MetadataMode.NONE) -> str:
        return self.node.get_content(metadata_mode=metadata_mode)

View on GitHub (pinned to afd0fef371)

Solutions

1. Use .get_content() instead — it dispatches on node type and works for all node classes
2. Type-check isinstance(nws.node, TextNode) before accessing .text
3. For custom node classes, subclass TextNode so the text API is available

Example fix

# before
print(nws.text)  # ValueError for ImageNode

# after
print(nws.get_content())  # type-aware content access

from llama_index.core.schema import TextNode
text = nws.text if isinstance(nws.node, TextNode) else nws.get_content()

from llama_index.core.schema import TextNode
def wraps_text_node(nws) -> bool:
    return isinstance(nws.node, TextNode)

When it happens

Trigger: Accessing .text on a NodeWithScore wrapping an ImageNode (or any non-TextNode), e.g. printing retrieved nodes or feeding them to a text-only response synthesizer.

Common situations: Multi-modal retrieval pipelines where image nodes flow through code written for text nodes; custom node classes subclassing BaseNode directly instead of TextNode.

Related errors

• No image found in node.
• Source object must be a single RelatedNodeInfo object
• Previous object must be a single RelatedNodeInfo object
• Next object must be a single RelatedNodeInfo object
• Parent object must be a single RelatedNodeInfo object

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