{"record":{"id":"477da2f5b3693b79","repo":"run-llama/llama_index","slug":"must-provide-sql-database","errorCode":null,"errorMessage":"Must provide sql_database","messagePattern":"Must provide sql_database","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/objects/table_node_mapping.py","lineNumber":39,"sourceCode":"\n\nclass SQLTableNodeMapping(BaseObjectNodeMapping[SQLTableSchema]):\n    \"\"\"SQL Table node mapping.\"\"\"\n\n    def __init__(self, sql_database: SQLDatabase) -> None:\n        self._sql_database = sql_database\n\n    @classmethod\n    def from_objects(\n        cls,\n        objs: Sequence[SQLTableSchema],\n        *args: Any,\n        sql_database: Optional[SQLDatabase] = None,\n        **kwargs: Any,\n    ) -> \"BaseObjectNodeMapping\":\n        \"\"\"Initialize node mapping.\"\"\"\n        if sql_database is None:\n            raise ValueError(\"Must provide sql_database\")\n        # ignore objs, since we are building from sql_database\n        return cls(sql_database)\n\n    def _add_object(self, obj: SQLTableSchema) -> None:\n        raise NotImplementedError\n\n    def to_node(self, obj: SQLTableSchema) -> TextNode:\n        \"\"\"To node.\"\"\"\n        # taken from existing schema logic\n        table_text = (\n            f\"Schema of table {obj.table_name}:\\n\"\n            f\"{self._sql_database.get_single_table_info(obj.table_name)}\\n\"\n        )\n\n        metadata = {\"name\": obj.table_name}\n\n        if obj.context_str is not None:\n            table_text += f\"Context of table {obj.table_name}:\\n\"","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/objects/table_node_mapping.py#L21-L57","documentation":"SQLTableNodeMapping.from_objects ignores the objs argument entirely (tables are discovered from the database) and requires the sql_database keyword. Passing only a list of SQLTableSchema objects without sql_database=... raises ValueError('Must provide sql_database').","triggerScenarios":"Calling SQLTableNodeMapping.from_objects(sql_table_schema_objs) or ObjectIndex.from_objects(sql_table_schema_objs, sql_database=None) without the sql_database keyword; commonly when copying SimpleObjectNodeMapping-style construction code.","commonSituations":"Building a table-schema ObjectIndex for text-to-SQL (SQLTableRetriever) and forgetting the SQLDatabase argument; refactoring code that previously constructed SQLTableNodeMapping(sql_database) directly.","solutions":["Pass the SQLDatabase: SQLTableNodeMapping.from_objects(objs, sql_database=sql_database)","Build a SQLDatabase first (e.g. SQLDatabase(engine, include_tables=[...])) and reuse it for both the mapping and the retriever","Ensure kwargs survive: from_objects(*args, sql_database=..., **kwargs) requires it as a keyword, not positional"],"exampleFix":"# before\nmapping = SQLTableNodeMapping.from_objects(table_schema_objs)  # ValueError: Must provide sql_database\n\n# after\nfrom llama_index.core import SQLDatabase\nsql_database = SQLDatabase(engine, include_tables=[\"city\", \"country\"])\nmapping = SQLTableNodeMapping.from_objects(table_schema_objs, sql_database=sql_database)","handlingStrategy":"validation","validationCode":"if sql_database is None:\n    raise ValueError(\"SQLTableNodeMapping.from_objects requires a SQLDatabase; build one via SQLDatabase(engine)\")\nmapping = SQLTableNodeMapping.from_objects(table_schemas, sql_database=sql_database)","typeGuard":"from llama_index.core import SQLDatabase\ndef is_valid_sql_database(db) -> bool:\n    return isinstance(db, SQLDatabase)","tryCatchPattern":"try:\n    mapping = SQLTableNodeMapping.from_objects(objs, sql_database=sql_database)\nexcept ValueError as e:\n    if \"Must provide sql_database\" in str(e):\n        raise ValueError(\"construct SQLDatabase(engine) first and pass it as sql_database=\") from e\n    raise","preventionTips":["Always create the SQLDatabase before building table mappings and pass it by keyword","Keep engine/database construction in one place so call sites cannot forget it"],"tags":["sql","object-index","configuration","validation"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}