run-llama/llama_index · error · ValueError

Objs cannot be loaded.

Error message

Objs cannot be loaded.

What it means

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.

Source

Thrown at llama-index-core/llama_index/core/objects/base_node_mapping.py:220

        obj_node_mapping_path = concat_dirs(persist_dir, obj_node_mapping_fname)
        try:
            with open(obj_node_mapping_path, "wb") as f:
                pickle.dump(self, f)
        except pickle.PickleError as err:
            raise ValueError("Objs is not pickleable") from err

    @classmethod
    def from_persist_dir(
        cls,
        persist_dir: str = DEFAULT_PERSIST_DIR,
        obj_node_mapping_fname: str = DEFAULT_PERSIST_FNAME,
    ) -> "SimpleObjectNodeMapping":
        obj_node_mapping_path = concat_dirs(persist_dir, obj_node_mapping_fname)
        try:
            with open(obj_node_mapping_path, "rb") as f:
                simple_object_node_mapping = _RestrictedUnpickler(f).load()
        except pickle.PickleError as err:
            raise ValueError("Objs cannot be loaded.") from err
        return simple_object_node_mapping

View on GitHub (pinned to afd0fef371)

Solutions

1. Check the chained exception (__cause__) to distinguish FileNotFoundError (file missing) from pickle.UnpicklingError (corrupt/invalid)
2. Re-create the persist dir: rebuild the ObjectIndex from your objects and persist again so a valid mapping pickle is written
3. If objects changed across versions, re-pickle with the current version rather than loading the old file
4. Bypass loading: rebuild the mapping in code and pass it as object_node_mapping= to ObjectIndex.from_persist_dir

Example fix

# before
mapping = SimpleObjectNodeMapping.from_persist_dir("./storage")  # ValueError: Objs cannot be loaded.

# after
mapping = SimpleObjectNodeMapping.from_objects(rebuild_objects())
obj_index = ObjectIndex.from_persist_dir(persist_dir="./storage", object_node_mapping=mapping)

import os
path = os.path.join(persist_dir, "object_node_mapping.pkl")
assert os.path.exists(path) and os.path.getsize(path) > 0, "mapping pickle missing/empty"

try:
    mapping = SimpleObjectNodeMapping.from_persist_dir(persist_dir)
except ValueError as e:
    if "cannot be loaded" in str(e):
        mapping = SimpleObjectNodeMapping.from_objects(rebuild_objects())  # rebuild fallback
    else:
        raise

When it happens

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

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

Related errors

• Unable to load from persist dir. The object_node_mapping can
• Objs is not pickleable
• Tool {tool.metadata.name} requires context. CodeActAgent onl
• FnNodeMapping does not support persist method.
• This object node mapping does not support persist method.

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