{"record":{"id":"6b3555c765c4698d","repo":"run-llama/llama_index","slug":"metadata-must-be-set","errorCode":null,"errorMessage":"Metadata must be set","messagePattern":"Metadata must be set","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/objects/table_node_mapping.py","lineNumber":74,"sourceCode":"        if obj.context_str is not None:\n            table_text += f\"Context of table {obj.table_name}:\\n\"\n            table_text += obj.context_str\n            metadata[\"context\"] = obj.context_str\n\n        table_identity = f\"{obj.table_name}{obj.context_str}\"\n\n        return TextNode(\n            id_=str(uuid.uuid5(namespace=uuid.NAMESPACE_DNS, name=table_identity)),\n            text=table_text,\n            metadata=metadata,\n            excluded_embed_metadata_keys=[\"name\", \"context\"],\n            excluded_llm_metadata_keys=[\"name\", \"context\"],\n        )\n\n    def _from_node(self, node: BaseNode) -> SQLTableSchema:\n        \"\"\"From node.\"\"\"\n        if node.metadata is None:\n            raise ValueError(\"Metadata must be set\")\n        return SQLTableSchema(\n            table_name=node.metadata[\"name\"], context_str=node.metadata.get(\"context\")\n        )\n\n    @property\n    def obj_node_mapping(self) -> Dict[int, Any]:\n        \"\"\"The mapping data structure between node and object.\"\"\"\n        raise NotImplementedError(\"Subclasses should implement this!\")\n\n    def persist(\n        self, persist_dir: str = ..., obj_node_mapping_fname: str = ...\n    ) -> None:\n        \"\"\"Persist objs.\"\"\"\n        raise NotImplementedError(\"Subclasses should implement this!\")\n\n    @classmethod\n    def from_persist_dir(\n        cls,","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/objects/table_node_mapping.py#L56-L92","documentation":"SQLTableNodeMapping._from_node reconstructs a SQLTableSchema from a retrieved node's metadata (keys 'name' and 'context'). It raises ValueError('Metadata must be set') when node.metadata is None. In practice nodes loaded from a docstore usually carry metadata={} (falsy-safe) so this fires mostly with hand-built TextNodes or nodes whose metadata was explicitly cleared.","triggerScenarios":"Calling mapping.from_node(node) on a TextNode constructed without metadata (TextNode(text=...) leaves metadata={} in current versions; older/manual nodes can be None), or calling the private _from_node directly during ObjectIndex retrieval when metadata was stripped.","commonSituations":"Unit tests with synthetic nodes; custom retrieval pipelines that rebuild nodes and drop metadata; docstores persisted by very old versions where metadata deserialized as None.","solutions":["Ensure nodes passed to from_node carry metadata={'name': <table_name>} (and optionally 'context')","Construct nodes through the mapping itself (mapping.to_node(SQLTableSchema(...))) so ids/metadata are consistent","Guard with `if not node.metadata:` before calling from_node and log which node is malformed"],"exampleFix":"# before\nnode = TextNode(text=\"Schema of table city: ...\")  # metadata missing\nschema = mapping.from_node(node)  # ValueError: Metadata must be set\n\n# after\nnode = mapping.to_node(SQLTableSchema(table_name=\"city\", context_str=\"city stats\"))\nschema = mapping.from_node(node)","handlingStrategy":"validation","validationCode":"if not node.metadata or \"name\" not in node.metadata:\n    raise ValueError(f\"node {node.id_} lacks metadata['name']; rebuild via mapping.to_node()\")\nschema = mapping.from_node(node)","typeGuard":"def node_has_table_metadata(node) -> bool:\n    return bool(node.metadata) and \"name\" in node.metadata","tryCatchPattern":"try:\n    schema = mapping.from_node(node)\nexcept ValueError as e:\n    if \"Metadata must be set\" in str(e):\n        skip_or_rebuild(node)  # log and skip malformed node instead of failing the loop\n    else:\n        raise","preventionTips":["Only feed nodes produced by mapping.to_node into from_node","In tests, build nodes through the mapping rather than raw TextNode(...)"],"tags":["sql","node-mapping","metadata","validation"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}