{"record":{"id":"e53c2464371c99e5","repo":"run-llama/llama_index","slug":"only-one-of-nodes-or-index-struct-can-be-provided","errorCode":null,"errorMessage":"Only one of nodes or index_struct can be provided.","messagePattern":"Only one of nodes or index_struct can be provided\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/base.py","lineNumber":52,"sourceCode":"\n    index_struct_cls: Type[IS]\n\n    def __init__(\n        self,\n        nodes: Optional[Sequence[BaseNode]] = None,\n        objects: Optional[Sequence[IndexNode]] = None,\n        index_struct: Optional[IS] = None,\n        storage_context: Optional[StorageContext] = None,\n        callback_manager: Optional[CallbackManager] = None,\n        transformations: Optional[List[TransformComponent]] = None,\n        show_progress: bool = False,\n        **kwargs: Any,\n    ) -> None:\n        \"\"\"Initialize with parameters.\"\"\"\n        if index_struct is None and nodes is None and objects is None:\n            raise ValueError(\"One of nodes, objects, or index_struct must be provided.\")\n        if index_struct is not None and nodes is not None and len(nodes) >= 1:\n            raise ValueError(\"Only one of nodes or index_struct can be provided.\")\n        # This is to explicitly make sure that the old UX is not used\n        if nodes is not None and len(nodes) >= 1 and not isinstance(nodes[0], BaseNode):\n            if isinstance(nodes[0], Document):\n                raise ValueError(\n                    \"The constructor now takes in a list of Node objects. \"\n                    \"Since you are passing in a list of Document objects, \"\n                    \"please use `from_documents` instead.\"\n                )\n            else:\n                raise ValueError(\"nodes must be a list of Node objects.\")\n\n        self._storage_context = storage_context or StorageContext.from_defaults()\n        self._docstore = self._storage_context.docstore\n        self._show_progress = show_progress\n        self._vector_store = self._storage_context.vector_store\n        self._graph_store = self._storage_context.graph_store\n        self._callback_manager = callback_manager or Settings.callback_manager\n","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/base.py#L34-L70","documentation":"BaseIndex's constructor forbids supplying both a populated nodes list and an index_struct. nodes means 'build a fresh index from these nodes' while index_struct means 'attach to an existing index skeleton'; providing both is contradictory and the constructor rejects it with ValueError.","triggerScenarios":"Calling an index constructor with both nodes=[...] and index_struct=... where nodes has length >= 1; copy/paste between the two construction patterns; wrapper code that always passes index_struct AND forwards user-supplied nodes.","commonSituations":"Migrating from the old nodes-based construction to index_struct-based construction and leaving both in the call; custom index subclasses whose __init__ defaults build an index_struct and then also forward nodes unconditionally.","solutions":["Pick one pattern: pass nodes to build new, or pass index_struct to attach existing — not both.","In subclass constructors, only forward nodes when the caller actually supplied them (guard with `nodes=nodes if nodes else None`).","To add data to an existing index, construct with index_struct and then call index.insert(...) / index.refresh(...) instead of passing nodes.","Use from_documents or from_nodes factories which handle the contract for you."],"exampleFix":"# before\nindex = VectorStoreIndex(\n    nodes=nodes,\n    index_struct=loaded_index_struct,  # both supplied -> ValueError\n)\n\n# after\nindex = VectorStoreIndex(index_struct=loaded_index_struct)\nindex.insert_nodes(nodes)  # add new data via the insert API","handlingStrategy":"validation","validationCode":"if index_struct is not None:\n    nodes = None  # attach mode; use index.insert_nodes() for new data\nelif nodes is None:\n    raise ValueError(\"Need nodes or index_struct\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Choose one construction pattern per call site and encode it in a helper function.","Use insert()/refresh() APIs to grow an existing index rather than mixing inputs."],"tags":["index","constructor","validation","base-index"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}