run-llama/llama_index · error · NotImplementedError

This object node mapping does not support persist method.

Error message

This object node mapping does not support persist method.

What it means

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.

Source

Thrown at llama-index-core/llama_index/core/objects/table_node_mapping.py:96

    @property
    def obj_node_mapping(self) -> Dict[int, Any]:
        """The mapping data structure between node and object."""
        raise NotImplementedError("Subclasses should implement this!")

    def persist(
        self, persist_dir: str = ..., obj_node_mapping_fname: str = ...
    ) -> None:
        """Persist objs."""
        raise NotImplementedError("Subclasses should implement this!")

    @classmethod
    def from_persist_dir(
        cls,
        persist_dir: str = DEFAULT_PERSIST_DIR,
        obj_node_mapping_fname: str = DEFAULT_PERSIST_FNAME,
    ) -> "SQLTableNodeMapping":
        raise NotImplementedError(
            "This object node mapping does not support persist method."
        )

View on GitHub (pinned to afd0fef371)

Solutions

1. Persist only the underlying index stores and rebuild SQLTableNodeMapping(sql_database) at load time
2. Pass object_node_mapping explicitly to ObjectIndex.from_persist_dir to bypass the automatic mapping load path
3. Branch on mapping type before calling persist in shared helper code

Example fix

# before
obj_index.persist("./storage")  # NotImplementedError from SQLTableNodeMapping.persist

# after
obj_index.index.storage_context.persist(persist_dir="./storage")
# reload:
#   index = load_index_from_storage(StorageContext.from_defaults(persist_dir="./storage"))
#   mapping = SQLTableNodeMapping(sql_database=sql_database)
#   obj_index = ObjectIndex(index=index, object_node_mapping=mapping)

from llama_index.core.objects import SQLTableNodeMapping
if isinstance(obj_index.object_node_mapping, SQLTableNodeMapping):
    obj_index.index.storage_context.persist(persist_dir=persist_dir)  # index only
else:
    obj_index.persist(persist_dir)

from llama_index.core.objects import SQLTableNodeMapping
def mapping_is_persistable(mapping) -> bool:
    return not isinstance(mapping, SQLTableNodeMapping)

try:
    obj_index.persist(persist_dir)
except NotImplementedError:
    # SQL mapping: persist index stores, rebuild mapping from SQLDatabase on load
    obj_index.index.storage_context.persist(persist_dir=persist_dir)

When it happens

Trigger: 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(...).

Common situations: 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.

Related errors

• FnNodeMapping does not support persist method.
• 'handoff' is a reserved tool name. Please use a different na
• Got empty streaming response
• Ref doc info not implemented for PropertyGraphIndex. All ins
• Struct Store Index does not support ref_doc_info.

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