{"record":{"id":"958c9a56ba705cbd","repo":"run-llama/llama_index","slug":"objs-cannot-be-loaded","errorCode":null,"errorMessage":"Objs cannot be loaded.","messagePattern":"Objs cannot be loaded\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/objects/base_node_mapping.py","lineNumber":220,"sourceCode":"        obj_node_mapping_path = concat_dirs(persist_dir, obj_node_mapping_fname)\n        try:\n            with open(obj_node_mapping_path, \"wb\") as f:\n                pickle.dump(self, f)\n        except pickle.PickleError as err:\n            raise ValueError(\"Objs is not pickleable\") from err\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    ) -> \"SimpleObjectNodeMapping\":\n        obj_node_mapping_path = concat_dirs(persist_dir, obj_node_mapping_fname)\n        try:\n            with open(obj_node_mapping_path, \"rb\") as f:\n                simple_object_node_mapping = _RestrictedUnpickler(f).load()\n        except pickle.PickleError as err:\n            raise ValueError(\"Objs cannot be loaded.\") from err\n        return simple_object_node_mapping\n","sourceCodeStart":202,"sourceCodeEnd":222,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/objects/base_node_mapping.py#L202-L222","documentation":"SimpleObjectNodeMapping.from_persist_dir opens <persist_dir>/object_node_mapping.pkl with a _RestrictedUnpickler and re-raises pickle.PickleError as ValueError('Objs cannot be loaded.'). Note the restricted unpickler only permits an allow-list of classes, so pickles referencing arbitrary outside classes can also fail at load time with pickle errors surfacing through this handler.","triggerScenarios":"Calling SimpleObjectNodeMapping.from_persist_dir (usually indirectly via ObjectIndex.from_persist_dir without an explicit mapping) on a missing, truncated, or corrupt .pkl file, or a pickle produced by an older/newer llama-index version whose object classes changed.","commonSituations":"Persist dir copied incompletely (only docstore/index files moved); partially-written pickle after a crash mid-persist; llama-index upgrade renamed/moved the persisted classes; mixing pickle protocols across Python versions (2->3).","solutions":["Check the chained exception (__cause__) to distinguish FileNotFoundError (file missing) from pickle.UnpicklingError (corrupt/invalid)","Re-create the persist dir: rebuild the ObjectIndex from your objects and persist again so a valid mapping pickle is written","If objects changed across versions, re-pickle with the current version rather than loading the old file","Bypass loading: rebuild the mapping in code and pass it as object_node_mapping= to ObjectIndex.from_persist_dir"],"exampleFix":"# before\nmapping = SimpleObjectNodeMapping.from_persist_dir(\"./storage\")  # ValueError: Objs cannot be loaded.\n\n# after\nmapping = SimpleObjectNodeMapping.from_objects(rebuild_objects())\nobj_index = ObjectIndex.from_persist_dir(persist_dir=\"./storage\", object_node_mapping=mapping)","handlingStrategy":"fallback","validationCode":"import os\npath = os.path.join(persist_dir, \"object_node_mapping.pkl\")\nassert os.path.exists(path) and os.path.getsize(path) > 0, \"mapping pickle missing/empty\"","typeGuard":null,"tryCatchPattern":"try:\n    mapping = SimpleObjectNodeMapping.from_persist_dir(persist_dir)\nexcept ValueError as e:\n    if \"cannot be loaded\" in str(e):\n        mapping = SimpleObjectNodeMapping.from_objects(rebuild_objects())  # rebuild fallback\n    else:\n        raise","preventionTips":["Write persist dirs atomically (temp dir + rename) so pickles are never half-written","Re-persist after llama-index upgrades instead of loading old pickles","Version your persist dirs and validate contents before loading"],"tags":["persistence","pickle","deserialization","object-index"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}