run-llama/llama_index · error · Exception

Unable to load from persist dir. The object_node_mapping can

Error message

Unable to load from persist dir. The object_node_mapping cannot be loaded.

What it means

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.

Source

Thrown at llama-index-core/llama_index/core/objects/base.py:206

        persist_dir: str = DEFAULT_PERSIST_DIR,
        object_node_mapping: Optional[BaseObjectNodeMapping] = None,
    ) -> "ObjectIndex":
        from llama_index.core.indices import load_index_from_storage

        storage_context = StorageContext.from_defaults(persist_dir=persist_dir)
        index = load_index_from_storage(storage_context)
        if object_node_mapping:
            return cls(index=index, object_node_mapping=object_node_mapping)
        else:
            # try to load object_node_mapping
            # assume SimpleObjectNodeMapping for simplicity as its only subclass
            # that supports this method
            try:
                object_node_mapping = SimpleObjectNodeMapping.from_persist_dir(
                    persist_dir=persist_dir
                )
            except Exception as err:
                raise Exception(
                    "Unable to load from persist dir. The object_node_mapping cannot be loaded."
                ) from err
            else:
                return cls(index=index, object_node_mapping=object_node_mapping)

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass the mapping explicitly at load time: ObjectIndex.from_persist_dir(persist_dir, object_node_mapping=my_mapping) after rebuilding it from your objects
2. Verify the persisted mapping file exists: <persist_dir>/object_node_mapping.pkl (default DEFAULT_PERSIST_FNAME) and was written by SimpleObjectNodeMapping.persist
3. Only use SimpleObjectNodeMapping (with pickleable objects) if you rely on automatic mapping persistence; SQL/Fn-based mappings must be reconstructed manually
4. Inspect the chained exception (__cause__) to see the real load failure (FileNotFoundError vs pickle.UnpicklingError)

Example fix

# before
obj_index = ObjectIndex.from_persist_dir(persist_dir="./storage")  # Exception: object_node_mapping cannot be loaded

# after
from llama_index.core.objects import SimpleObjectNodeMapping
mapping = SimpleObjectNodeMapping.from_objects(my_objs)
obj_index = ObjectIndex.from_persist_dir(persist_dir="./storage", object_node_mapping=mapping)

import os
from llama_index.core.objects.base_node_mapping import DEFAULT_PERSIST_FNAME

if not os.path.exists(os.path.join(persist_dir, DEFAULT_PERSIST_FNAME)):
    # mapping file absent: plan to pass object_node_mapping explicitly
    mapping = SimpleObjectNodeMapping.from_objects(rebuild_objects())
else:
    mapping = None

try:
    obj_index = ObjectIndex.from_persist_dir(persist_dir, object_node_mapping=mapping)
except Exception as e:
    cause = e.__cause__
    if isinstance(cause, FileNotFoundError):
        obj_index = ObjectIndex.from_persist_dir(persist_dir, object_node_mapping=SimpleObjectNodeMapping.from_objects(rebuild_objects()))
    else:
        raise

When it happens

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

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

Related errors

• Objs cannot be loaded.
• 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/f65e33552d759b58. Report an issue: GitHub.