{"record":{"id":"f65e33552d759b58","repo":"run-llama/llama_index","slug":"unable-to-load-from-persist-dir-the-object-node-m","errorCode":null,"errorMessage":"Unable to load from persist dir. The object_node_mapping cannot be loaded.","messagePattern":"Unable to load from persist dir\\. The object_node_mapping cannot be loaded\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/objects/base.py","lineNumber":206,"sourceCode":"        persist_dir: str = DEFAULT_PERSIST_DIR,\n        object_node_mapping: Optional[BaseObjectNodeMapping] = None,\n    ) -> \"ObjectIndex\":\n        from llama_index.core.indices import load_index_from_storage\n\n        storage_context = StorageContext.from_defaults(persist_dir=persist_dir)\n        index = load_index_from_storage(storage_context)\n        if object_node_mapping:\n            return cls(index=index, object_node_mapping=object_node_mapping)\n        else:\n            # try to load object_node_mapping\n            # assume SimpleObjectNodeMapping for simplicity as its only subclass\n            # that supports this method\n            try:\n                object_node_mapping = SimpleObjectNodeMapping.from_persist_dir(\n                    persist_dir=persist_dir\n                )\n            except Exception as err:\n                raise Exception(\n                    \"Unable to load from persist dir. The object_node_mapping cannot be loaded.\"\n                ) from err\n            else:\n                return cls(index=index, object_node_mapping=object_node_mapping)\n","sourceCodeStart":188,"sourceCodeEnd":211,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/objects/base.py#L188-L211","documentation":"ObjectIndex.from_persist_dir first loads the underlying index from storage, then, if no object_node_mapping argument was supplied, tries to load a SimpleObjectNodeMapping pickle from the persist directory. If that load raises (missing pickle file, unpickling error, restricted-class error), it wraps the cause in a generic Exception. The index itself loaded fine; only the object<->node mapping could not be restored.","triggerScenarios":"Calling ObjectIndex.from_persist_dir(persist_dir) where the directory was written by an ObjectIndex whose mapping was not a SimpleObjectNodeMapping (e.g. FnObjectNodeMapping or SQLTableNodeMapping, which cannot persist), or where the persisted pickle is missing/corrupt, or contains objects the _RestrictedUnpickler refuses.","commonSituations":"Persisting an ObjectIndex built over SQL tables or function-based mappings (they silently skip/never wrote the mapping file), moving persist dirs between machines without copying all files, unpickling objects referencing classes that moved/renamed between llama-index versions.","solutions":["Pass the mapping explicitly at load time: ObjectIndex.from_persist_dir(persist_dir, object_node_mapping=my_mapping) after rebuilding it from your objects","Verify the persisted mapping file exists: <persist_dir>/object_node_mapping.pkl (default DEFAULT_PERSIST_FNAME) and was written by SimpleObjectNodeMapping.persist","Only use SimpleObjectNodeMapping (with pickleable objects) if you rely on automatic mapping persistence; SQL/Fn-based mappings must be reconstructed manually","Inspect the chained exception (__cause__) to see the real load failure (FileNotFoundError vs pickle.UnpicklingError)"],"exampleFix":"# before\nobj_index = ObjectIndex.from_persist_dir(persist_dir=\"./storage\")  # Exception: object_node_mapping cannot be loaded\n\n# after\nfrom llama_index.core.objects import SimpleObjectNodeMapping\nmapping = SimpleObjectNodeMapping.from_objects(my_objs)\nobj_index = ObjectIndex.from_persist_dir(persist_dir=\"./storage\", object_node_mapping=mapping)","handlingStrategy":"try-catch","validationCode":"import os\nfrom llama_index.core.objects.base_node_mapping import DEFAULT_PERSIST_FNAME\n\nif not os.path.exists(os.path.join(persist_dir, DEFAULT_PERSIST_FNAME)):\n    # mapping file absent: plan to pass object_node_mapping explicitly\n    mapping = SimpleObjectNodeMapping.from_objects(rebuild_objects())\nelse:\n    mapping = None","typeGuard":null,"tryCatchPattern":"try:\n    obj_index = ObjectIndex.from_persist_dir(persist_dir, object_node_mapping=mapping)\nexcept Exception as e:\n    cause = e.__cause__\n    if isinstance(cause, FileNotFoundError):\n        obj_index = ObjectIndex.from_persist_dir(persist_dir, object_node_mapping=SimpleObjectNodeMapping.from_objects(rebuild_objects()))\n    else:\n        raise","preventionTips":["Always persist with SimpleObjectNodeMapping if you intend to auto-load later","Pass object_node_mapping explicitly on load instead of relying on the pickle path","Keep the entire persist dir together (never copy index files without the mapping pickle)"],"tags":["persistence","object-index","pickle","deserialization"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}