run-llama/llama_index · error · ValueError

Expected to load a single index, but got {len(indices)} inst

Error message

Expected to load a single index, but got {len(indices)} instead. Please specify index_id.

What it means

load_index_from_storage() requires a unique index: when load_indices_from_storage returns more than one (the index store persisted several index_structs), it raises ValueError asking you to disambiguate with index_id. The count is interpolated into the message.

Source

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

            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.

    Args:
        storage_context (StorageContext): storage context containing
            docstore, index store and vector store.

View on GitHub (pinned to afd0fef371)

Solutions

Pass the specific index_id: load_index_from_storage(storage_context, index_id='<id>') — the ids are the index_struct ids you persisted (also visible via storage_context.index_store.index_structs()).
Inspect available ids before loading: [s.index_id for s in storage_context.index_store.index_structs()].
Or call load_indices_from_storage to get all of them and select programmatically.

Example fix

# before
index = load_index_from_storage(storage_context)  # got 2 instead

# after
ids = [s.index_id for s in storage_context.index_store.index_structs()]
index = load_index_from_storage(storage_context, index_id=ids[0])

Defensive patterns

Strategy: validation

Validate before calling

ids = [s.index_id for s in storage_context.index_store.index_structs()]
assert len(ids) >= 1, "no indices to load"
if len(ids) > 1:
    index = load_index_from_storage(storage_context, index_id=ids[0])  # disambiguate
else:
    index = load_index_from_storage(storage_context)

Try / catch

try:
    index = load_index_from_storage(storage_context)
except ValueError as e:
    if "Please specify index_id" in str(e):
        ids = [s.index_id for s in storage_context.index_store.index_structs()]
        index = load_index_from_storage(storage_context, index_id=ids[0])
    else:
        raise

Prevention

Store index_id alongside the persist dir when you persist (index.index_id).
Use one persist_dir per index to keep loads unambiguous.
Inspect index_structs() before loading in generic tooling.

When it happens

Trigger: Persisting multiple indices into one storage_context (e.g. a VectorStoreIndex and a SummaryIndex sharing a persist_dir), then calling load_index_from_storage without index_id; re-running builds that accumulate index structs in the same store.

Common situations: One persist_dir holding a document index plus a summary/keyword index; iterative development saving several index versions into the same directory; shared storage context reused across index builds.

Related errors

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