{"record":{"id":"3110b9c0cf32d5a8","repo":"run-llama/llama_index","slug":"this-object-node-mapping-does-not-support-persist-3110b9","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/tool_node_mapping.py","lineNumber":61,"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    ) -> \"BaseToolNodeMapping\":\n        raise NotImplementedError(\n            \"This object node mapping does not support persist method.\"\n        )\n\n\nclass SimpleToolNodeMapping(BaseToolNodeMapping):\n    \"\"\"\n    Simple Tool mapping.\n\n    In this setup, we assume that the tool name is unique, and\n    that the list of all tools are stored in memory.\n\n    \"\"\"\n\n    def __init__(self, objs: Optional[Sequence[BaseTool]] = None) -> None:\n        objs = objs or []\n        self._tools = {tool.metadata.name: tool for tool in objs}\n\n    @classmethod","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/objects/tool_node_mapping.py#L43-L79","documentation":"BaseToolNodeMapping (and by inheritance SimpleToolNodeMapping) does not implement persistence: from_persist_dir raises NotImplementedError with this message. Tools typically wrap live engines/LLM clients that cannot be pickled, so the mapping must be rebuilt from the actual tool objects at runtime.","triggerScenarios":"Calling BaseToolNodeMapping.from_persist_dir(persist_dir) directly, or ObjectIndex.from_persist_dir without object_node_mapping when the persisted index was built over tools — the default load path attempts to load a mapping and fails.","commonSituations":"Persisting a tool ObjectIndex (e.g. for an agent) and trying to restore it in a new process; assuming every ObjectIndex persists the same way as the SimpleObjectNodeMapping examples in the docs.","solutions":["Rebuild the tools in code and pass the mapping at load: ObjectIndex.from_persist_dir(persist_dir, object_node_mapping=SimpleToolNodeMapping.from_objects(tools))","Persist only the index stores (index.storage_context.persist(...)) and reconstruct the ObjectIndex around the loaded index","Keep tool definitions in configuration so tools can be recreated deterministically on startup"],"exampleFix":"# before\nobj_index = ObjectIndex.from_persist_dir(\"./storage\")  # mapping load fails for tools\n\n# after\ntools = [FunctionTool.from_defaults(fn=fn_a), FunctionTool.from_defaults(fn=fn_b)]\nmapping = SimpleToolNodeMapping.from_objects(tools)\nobj_index = ObjectIndex.from_persist_dir(\"./storage\", object_node_mapping=mapping)","handlingStrategy":"fallback","validationCode":"# rebuild mapping from live tools and pass it explicitly — never rely on auto-load for tool mappings\nmapping = SimpleToolNodeMapping.from_objects(build_tools())\nobj_index = ObjectIndex.from_persist_dir(persist_dir, object_node_mapping=mapping)","typeGuard":"def mapping_supports_disk_load(mapping_cls) -> bool:\n    from llama_index.core.objects import SimpleObjectNodeMapping\n    return mapping_cls is SimpleObjectNodeMapping","tryCatchPattern":"try:\n    obj_index = ObjectIndex.from_persist_dir(persist_dir)\nexcept (NotImplementedError, Exception) as e:\n    if \"persist\" in str(e) or \"object_node_mapping\" in str(e):\n        mapping = SimpleToolNodeMapping.from_objects(build_tools())\n        obj_index = ObjectIndex.from_persist_dir(persist_dir, object_node_mapping=mapping)\n    else:\n        raise","preventionTips":["Treat tool definitions as code/config to re-create, not data to persist","Persist only index stores for tool-based ObjectIndexes"],"tags":["tools","persistence","not-implemented","object-index"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}