run-llama/llama_index · error · ValueError

sql_database must be specified

Error message

sql_database must be specified

What it means

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.

Source

Thrown at llama-index-core/llama_index/core/indices/struct_store/sql.py:78

    """

    index_struct_cls = SQLStructTable

    def __init__(
        self,
        nodes: Optional[Sequence[BaseNode]] = None,
        index_struct: Optional[SQLStructTable] = None,
        sql_database: Optional[SQLDatabase] = None,
        table_name: Optional[str] = None,
        table: Optional[Table] = None,
        ref_doc_id_column: Optional[str] = None,
        sql_context_container: Optional[SQLContextContainer] = None,
        **kwargs: Any,
    ) -> None:
        """Initialize params."""
        if sql_database is None:
            raise ValueError("sql_database must be specified")
        self.sql_database = sql_database
        # needed here for data extractor
        self._ref_doc_id_column = ref_doc_id_column
        self._table_name = table_name
        self._table = table

        # if documents aren't specified, pass in a blank []
        if index_struct is None:
            nodes = nodes or []

        super().__init__(
            nodes=nodes,
            index_struct=index_struct,
            **kwargs,
        )

        # TODO: index_struct context_dict is deprecated,
        # we're migrating storage of information to here.

View on GitHub (pinned to afd0fef371)

Solutions

1. 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').
2. 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.
3. Verify the argument type — it must be llama_index.core.utilities.sql_database.SQLDatabase, not a sqlalchemy.Engine or connection string.

Example fix

// before
index = SQLStructStoreIndex(nodes, table_name="city_stats")

// after
from llama_index.core.utilities import SQLDatabase
sql_database = SQLDatabase(engine, include_tables=["city_stats"])
index = SQLStructStoreIndex(nodes, sql_database=sql_database, table_name="city_stats")

from llama_index.core.utilities import SQLDatabase

def build_sql_index(nodes, engine, table_name):
    sql_database = SQLDatabase(engine, include_tables=[table_name])
    assert isinstance(sql_database, SQLDatabase)
    return SQLStructStoreIndex(nodes, sql_database=sql_database, table_name=table_name)

from llama_index.core.utilities.sql_database import SQLDatabase

def is_sql_database(obj: object) -> bool:
    return isinstance(obj, SQLDatabase)

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• context_dict must be provided. There is currently no table c
• embeddings_cache must be of type BaseKVStore
• embeddings_cache must be defined
• Did not find {key}, please add an environment variable `{env
• Cannot add two handlers of the same type {type(new_handler)}

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