run-llama/llama_index · error · ValueError

One of nodes, objects, or index_struct must be provided.

Error message

One of nodes, objects, or index_struct must be provided.

What it means

The BaseIndex constructor requires exactly one source of index material: pre-built nodes, IndexNode objects, or an existing index_struct (the serialized index skeleton used when rehydrating an index). If all three are None there is nothing to build from, so it raises ValueError. This is a constructor-contract error, not a data error.

Source

Thrown at llama-index-core/llama_index/core/indices/base.py:50

    """

    index_struct_cls: Type[IS]

    def __init__(
        self,
        nodes: Optional[Sequence[BaseNode]] = None,
        objects: Optional[Sequence[IndexNode]] = None,
        index_struct: Optional[IS] = None,
        storage_context: Optional[StorageContext] = None,
        callback_manager: Optional[CallbackManager] = None,
        transformations: Optional[List[TransformComponent]] = None,
        show_progress: bool = False,
        **kwargs: Any,
    ) -> None:
        """Initialize with parameters."""
        if index_struct is None and nodes is None and objects is None:
            raise ValueError("One of nodes, objects, or index_struct must be provided.")
        if index_struct is not None and nodes is not None and len(nodes) >= 1:
            raise ValueError("Only one of nodes or index_struct can be provided.")
        # This is to explicitly make sure that the old UX is not used
        if nodes is not None and len(nodes) >= 1 and not isinstance(nodes[0], BaseNode):
            if isinstance(nodes[0], Document):
                raise ValueError(
                    "The constructor now takes in a list of Node objects. "
                    "Since you are passing in a list of Document objects, "
                    "please use `from_documents` instead."
                )
            else:
                raise ValueError("nodes must be a list of Node objects.")

        self._storage_context = storage_context or StorageContext.from_defaults()
        self._docstore = self._storage_context.docstore
        self._show_progress = show_progress
        self._vector_store = self._storage_context.vector_store
        self._graph_store = self._storage_context.graph_store

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass index_struct=self.index_struct from your subclass (the standard pattern: super().__init__(nodes=..., index_struct=self.index_struct, ...)).
2. If you have documents, use the class factory: IndexClass.from_documents(documents) instead of the raw constructor.
3. If you have parsed nodes, pass them via nodes=[...].
4. If rehydrating a persisted index, load the index_struct from storage and pass it, or use the storage context reload helpers.

Example fix

# before
class MyIndex(BaseIndex):
    def __init__(self, *args, **kwargs):
        super().__init__()  # no nodes/objects/index_struct -> ValueError

# after
class MyIndex(BaseIndex):
    index_struct_cls = MyIndexStruct
    def __init__(self, nodes=None, index_struct=None, **kwargs):
        index_struct = index_struct or MyIndexStruct()
        super().__init__(nodes=nodes, index_struct=index_struct, **kwargs)

if nodes is None and objects is None and index_struct is None:
    raise ValueError("Supply nodes, objects, or index_struct before constructing the index")

def has_index_inputs(nodes, objects, index_struct) -> bool:
    return any([nodes, objects, index_struct])

When it happens

Trigger: Calling BaseIndex(...) (or a subclass constructor) with no nodes, objects, or index_struct; writing a custom index subclass whose __init__ forwards **kwargs but drops the required arguments; calling a subclass constructor directly instead of a factory like from_documents or as_index.

Common situations: Custom index implementations that forget to pass index_struct up to super().__init__; accidentally invoking the constructor when intending to call a classmethod; refactors that pass StorageContext but omit index_struct.

Related errors

• Only one of nodes or index_struct can be provided.
• The constructor now takes in a list of Node objects. Since y
• nodes must be a list of Node objects.
• All agents must have a name in a multi-agent workflow
• All agents must have a description in a multi-agent workflow

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