{"record":{"id":"df2ddf24b716417f","repo":"run-llama/llama_index","slug":"sql-database-must-be-specified","errorCode":null,"errorMessage":"sql_database must be specified","messagePattern":"sql_database must be specified","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/struct_store/sql.py","lineNumber":78,"sourceCode":"\n    \"\"\"\n\n    index_struct_cls = SQLStructTable\n\n    def __init__(\n        self,\n        nodes: Optional[Sequence[BaseNode]] = None,\n        index_struct: Optional[SQLStructTable] = None,\n        sql_database: Optional[SQLDatabase] = None,\n        table_name: Optional[str] = None,\n        table: Optional[Table] = None,\n        ref_doc_id_column: Optional[str] = None,\n        sql_context_container: Optional[SQLContextContainer] = None,\n        **kwargs: Any,\n    ) -> None:\n        \"\"\"Initialize params.\"\"\"\n        if sql_database is None:\n            raise ValueError(\"sql_database must be specified\")\n        self.sql_database = sql_database\n        # needed here for data extractor\n        self._ref_doc_id_column = ref_doc_id_column\n        self._table_name = table_name\n        self._table = table\n\n        # if documents aren't specified, pass in a blank []\n        if index_struct is None:\n            nodes = nodes or []\n\n        super().__init__(\n            nodes=nodes,\n            index_struct=index_struct,\n            **kwargs,\n        )\n\n        # TODO: index_struct context_dict is deprecated,\n        # we're migrating storage of information to here.","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/struct_store/sql.py#L60-L96","documentation":"SQLStructStoreIndex.__init__ raises ValueError('sql_database must be specified') when the sql_database argument is None. The index wraps a SQLAlchemy database (llama_index.core.utilities.SQLDatabase) and cannot construct table context or extract datapoints without one. sql_database has no default and is not derivable from the other arguments (table_name, table, nodes), so omitting it is always a hard failure.","triggerScenarios":"Calling SQLStructStoreIndex(nodes=...) or GPTSQLStructStoreIndex(...) without sql_database; loading a persisted index via load_index_from_storage where the storage context has no way to reconstruct the SQLDatabase; passing an engine/URL string instead of a SQLDatabase object and separately forgetting the real argument.","commonSituations":"Copy-pasting examples that build documents first and deferring the engine setup; upgrading from very old examples where an engine was passed positionally and the signature changed; building the index from code where the SQLAlchemy engine is created later (e.g. lazy init in another function).","solutions":["Create the database object and pass it: sql_database = SQLDatabase(engine, include_tables=['my_table']) then SQLStructStoreIndex(nodes, sql_database=sql_database, table_name='my_table').","If loading from storage, re-supply sql_database at query time: SQLStructStoreIndex(...) must be constructed with a live SQLDatabase; persist only index_struct/nodes and rebuild the wrapper with the engine.","Verify the argument type — it must be llama_index.core.utilities.sql_database.SQLDatabase, not a sqlalchemy.Engine or connection string."],"exampleFix":"// before\nindex = SQLStructStoreIndex(nodes, table_name=\"city_stats\")\n\n// after\nfrom llama_index.core.utilities import SQLDatabase\nsql_database = SQLDatabase(engine, include_tables=[\"city_stats\"])\nindex = SQLStructStoreIndex(nodes, sql_database=sql_database, table_name=\"city_stats\")","handlingStrategy":"validation","validationCode":"from llama_index.core.utilities import SQLDatabase\n\ndef build_sql_index(nodes, engine, table_name):\n    sql_database = SQLDatabase(engine, include_tables=[table_name])\n    assert isinstance(sql_database, SQLDatabase)\n    return SQLStructStoreIndex(nodes, sql_database=sql_database, table_name=table_name)","typeGuard":"from llama_index.core.utilities.sql_database import SQLDatabase\n\ndef is_sql_database(obj: object) -> bool:\n    return isinstance(obj, SQLDatabase)","tryCatchPattern":null,"preventionTips":["Treat SQLDatabase as a required constructor arg: fail fast in your own builder if engine/database setup fails.","Never pass a raw sqlalchemy.Engine or connection URL where SQLDatabase is expected — wrap it first.","For persisted SQL indexes, store the engine config separately and reconstruct sql_database at load time."],"tags":["sql","constructor","config","llama-index"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}