{"record":{"id":"05189ad163f3b5a0","repo":"run-llama/llama_index","slug":"this-object-node-mapping-does-not-support-persist","errorCode":null,"errorMessage":"This object node mapping does not support persist method.","messagePattern":"This object node mapping does not support persist method\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/objects/table_node_mapping.py","lineNumber":96,"sourceCode":"\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,\n        persist_dir: str = DEFAULT_PERSIST_DIR,\n        obj_node_mapping_fname: str = DEFAULT_PERSIST_FNAME,\n    ) -> \"SQLTableNodeMapping\":\n        raise NotImplementedError(\n            \"This object node mapping does not support persist method.\"\n        )\n","sourceCodeStart":78,"sourceCodeEnd":99,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/objects/table_node_mapping.py#L78-L99","documentation":"SQLTableNodeMapping derives all information live from the connected SQLDatabase, so it has no serializable state; both persist and from_persist_dir raise NotImplementedError. The mapping is meant to be re-created from the database, not persisted.","triggerScenarios":"Calling obj_index.persist(persist_dir) on an ObjectIndex whose mapping is SQLTableNodeMapping, or calling SQLTableNodeMapping.from_persist_dir(...); typically via ObjectIndex.from_objects(sql_table_schemas, sql_database=...).persist(...).","commonSituations":"Trying to save a SQLTableRetriever/ObjectIndex setup for reuse across sessions using the generic persist API; generic persistence wrappers that call persist on every mapping type.","solutions":["Persist only the underlying index stores and rebuild SQLTableNodeMapping(sql_database) at load time","Pass object_node_mapping explicitly to ObjectIndex.from_persist_dir to bypass the automatic mapping load path","Branch on mapping type before calling persist in shared helper code"],"exampleFix":"# before\nobj_index.persist(\"./storage\")  # NotImplementedError from SQLTableNodeMapping.persist\n\n# after\nobj_index.index.storage_context.persist(persist_dir=\"./storage\")\n# reload:\n#   index = load_index_from_storage(StorageContext.from_defaults(persist_dir=\"./storage\"))\n#   mapping = SQLTableNodeMapping(sql_database=sql_database)\n#   obj_index = ObjectIndex(index=index, object_node_mapping=mapping)","handlingStrategy":"type-guard","validationCode":"from llama_index.core.objects import SQLTableNodeMapping\nif isinstance(obj_index.object_node_mapping, SQLTableNodeMapping):\n    obj_index.index.storage_context.persist(persist_dir=persist_dir)  # index only\nelse:\n    obj_index.persist(persist_dir)","typeGuard":"from llama_index.core.objects import SQLTableNodeMapping\ndef mapping_is_persistable(mapping) -> bool:\n    return not isinstance(mapping, SQLTableNodeMapping)","tryCatchPattern":"try:\n    obj_index.persist(persist_dir)\nexcept NotImplementedError:\n    # SQL mapping: persist index stores, rebuild mapping from SQLDatabase on load\n    obj_index.index.storage_context.persist(persist_dir=persist_dir)","preventionTips":["Re-create SQLTableNodeMapping from the live database on startup; never plan to persist it","Centralize persistence in a helper that branches on mapping type"],"tags":["sql","persistence","not-implemented","api-limitation"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}