{"record":{"id":"10fa260e4bb203e3","repo":"run-llama/llama_index","slug":"sql-database-must-be-provided","errorCode":null,"errorMessage":"sql_database must be provided.","messagePattern":"sql_database must be provided\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/common/struct_store/base.py","lineNumber":59,"sourceCode":"        table_context_task (Optional[str]): The query to perform\n            on the table context. A default query string is used\n            if none is provided by the user.\n\n    \"\"\"\n\n    def __init__(\n        self,\n        sql_database: SQLDatabase,\n        llm: Optional[LLM] = None,\n        text_splitter: Optional[TextSplitter] = None,\n        table_context_prompt: Optional[BasePromptTemplate] = None,\n        refine_table_context_prompt: Optional[BasePromptTemplate] = None,\n        table_context_task: Optional[str] = None,\n    ) -> None:\n        \"\"\"Initialize params.\"\"\"\n        # TODO: take in an entire index instead of forming a response builder\n        if sql_database is None:\n            raise ValueError(\"sql_database must be provided.\")\n        self._sql_database = sql_database\n        self._text_splitter = text_splitter\n        self._llm = llm or Settings.llm\n        self._prompt_helper = Settings._prompt_helper or PromptHelper.from_llm_metadata(\n            self._llm.metadata,\n        )\n        self._callback_manager = Settings.callback_manager\n        self._table_context_prompt = (\n            table_context_prompt or DEFAULT_TABLE_CONTEXT_PROMPT\n        )\n        self._refine_table_context_prompt = (\n            refine_table_context_prompt or DEFAULT_REFINE_TABLE_CONTEXT_PROMPT_SEL\n        )\n        self._table_context_task = table_context_task or DEFAULT_TABLE_CONTEXT_QUERY\n\n    def build_all_context_from_documents(\n        self,\n        documents_dict: Dict[str, List[BaseNode]],","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/common/struct_store/base.py#L41-L77","documentation":"SQLStructStoreIndexContext (the base context object for SQL table extraction) requires a SQLDatabase instance; it validates that sql_database is not None at construction. The parameter is typed as SQLDatabase (not Optional) but the None check exists because older call signatures and duck-typed callers could pass None.","triggerScenarios":"Constructing BaseSQLStructStoreIndexContext (or a subclass like SQLStructStoreIndexContext) with sql_database=None; omitting the sql_database keyword when subclass constructors don't enforce defaults.","commonSituations":"Building a SQLStructIndex/PGVectorSQLStructStoreIndex without wiring up the SQLDatabase(engine) first; custom subclasses that forward **kwargs and accidentally swallow sql_database; test stubs passing None placeholders.","solutions":["Create the database wrapper and pass it: from llama_index.core.sql_database import SQLDatabase; sql_db = SQLDatabase(engine, include_tables=['my_table']).","If building SQLStructIndex.from_documents, make sure the sql_database kwarg is actually forwarded in your call.","Audit custom context subclasses to ensure sql_database is threaded through to super().__init__."],"exampleFix":"# before\nindex = SQLStructIndex.from_documents(docs, sql_database=None)  # ValueError\n\n# after\nfrom llama_index.core import SQLDatabase\nfrom sqlalchemy import create_engine\nengine = create_engine(\"sqlite:///data.db\")\nsql_db = SQLDatabase(engine, include_tables=[\"items\"])\nindex = SQLStructIndex.from_documents(docs, sql_database=sql_db)","handlingStrategy":"validation","validationCode":"if sql_database is None:\n    raise ValueError(\"Create SQLDatabase(engine) and pass sql_database=<instance>\")","typeGuard":"def has_sql_database(db) -> bool:\n    from llama_index.core.sql_database import SQLDatabase\n    return isinstance(db, SQLDatabase)","tryCatchPattern":null,"preventionTips":["Construct SQLDatabase(engine) once at app startup and inject it wherever SQL indexes are built.","Fail fast on missing engine configuration instead of passing None through."],"tags":["sql","validation","constructor","struct-store"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}