run-llama/llama_index · error · ValueError

No index in storage context, check if you specified the righ

Error message

No index in storage context, check if you specified the right persist_dir.

What it means

load_index_from_storage(storage_context) loads every index found in the storage context's index store and expects exactly one. If load_indices_from_storage returns zero indices — the index store has no index_structs — it raises ValueError pointing at the persist_dir. This means the directory either is not a persisted llama-index storage dir or contains no index (e.g. only a docstore).

Source

Thrown at llama-index-core/llama_index/core/indices/loading.py:38

    Args:
        storage_context (StorageContext): storage context containing
            docstore, index store and vector store.
        index_id (Optional[str]): ID of the index to load.
            Defaults to None, which assumes there's only a single index
            in the index store and load it.
        **kwargs: Additional keyword args to pass to the index constructors.

    """
    index_ids: Optional[Sequence[str]]
    if index_id is None:
        index_ids = None
    else:
        index_ids = [index_id]

    indices = load_indices_from_storage(storage_context, index_ids=index_ids, **kwargs)

    if len(indices) == 0:
        raise ValueError(
            "No index in storage context, check if you specified the right persist_dir."
        )
    elif len(indices) > 1:
        raise ValueError(
            f"Expected to load a single index, but got {len(indices)} instead. "
            "Please specify index_id."
        )

    return indices[0]


def load_indices_from_storage(
    storage_context: StorageContext,
    index_ids: Optional[Sequence[str]] = None,
    **kwargs: Any,
) -> List[BaseIndex]:
    """
    Load multiple indices from storage context.

View on GitHub (pinned to afd0fef371)

Solutions

Confirm the target dir actually contains persisted storage: look for default_doc_store.json / docstore.json and an index store file (default_index_store.json) with index_structs entries.
Create the index first: VectorStoreIndex.from_documents(docs) then index.storage_context.persist(persist_dir=...) so the index store is written.
If multiple or optional indices are possible, call load_indices_from_storage directly and handle the empty list yourself instead of the singular helper.

Example fix

# before
storage_context = StorageContext.from_defaults(persist_dir="./empty_dir")
index = load_index_from_storage(storage_context)  # ValueError

# after
# ensure an index was persisted first
VectorStoreIndex.from_documents(docs).storage_context.persist(persist_dir="./storage")
storage_context = StorageContext.from_defaults(persist_dir="./storage")
index = load_index_from_storage(storage_context)

Defensive patterns

Strategy: validation

Validate before calling

import os
from llama_index.core.storage.storage_context import StorageContext

persist_dir = "./storage"
assert os.path.isdir(persist_dir) and os.listdir(persist_dir), f"{persist_dir} is empty or missing"
storage_context = StorageContext.from_defaults(persist_dir=persist_dir)
assert len(storage_context.index_store.index_structs()) > 0, "no index persisted in this dir"
index = load_index_from_storage(storage_context)

Try / catch

try:
    index = load_index_from_storage(storage_context)
except ValueError as e:
    if "No index in storage context" in str(e):
        index = build_and_persist_index(persist_dir)  # build once, then load
    else:
        raise

Prevention

Check persist_dir exists and contains index-store JSON before loading.
Persist via index.storage_context.persist(dir) right after building so the dir is complete.
On first run, branch to index construction instead of load.

When it happens

Trigger: StorageContext.from_defaults(persist_dir=...) pointing at an empty/never-persisted directory; persisting with StorageContext without any index (docstore-only persistence) and later calling load_index_from_storage; typos in the persist_dir path that silently create an empty dir.

Common situations: First run of an app before any index was saved; pointing at the wrong directory after moving storage; mixing up persist of documents vs persist of index; crashing between docstore.persist and index persist leaving a half-written dir.

Related errors

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