run-llama/llama_index · error · ValueError

Must provide sql_database

Error message

Must provide sql_database

What it means

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').

Source

Thrown at llama-index-core/llama_index/core/objects/table_node_mapping.py:39

class SQLTableNodeMapping(BaseObjectNodeMapping[SQLTableSchema]):
    """SQL Table node mapping."""

    def __init__(self, sql_database: SQLDatabase) -> None:
        self._sql_database = sql_database

    @classmethod
    def from_objects(
        cls,
        objs: Sequence[SQLTableSchema],
        *args: Any,
        sql_database: Optional[SQLDatabase] = None,
        **kwargs: Any,
    ) -> "BaseObjectNodeMapping":
        """Initialize node mapping."""
        if sql_database is None:
            raise ValueError("Must provide sql_database")
        # ignore objs, since we are building from sql_database
        return cls(sql_database)

    def _add_object(self, obj: SQLTableSchema) -> None:
        raise NotImplementedError

    def to_node(self, obj: SQLTableSchema) -> TextNode:
        """To node."""
        # taken from existing schema logic
        table_text = (
            f"Schema of table {obj.table_name}:\n"
            f"{self._sql_database.get_single_table_info(obj.table_name)}\n"
        )

        metadata = {"name": obj.table_name}

        if obj.context_str is not None:
            table_text += f"Context of table {obj.table_name}:\n"

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass the SQLDatabase: SQLTableNodeMapping.from_objects(objs, sql_database=sql_database)
2. Build a SQLDatabase first (e.g. SQLDatabase(engine, include_tables=[...])) and reuse it for both the mapping and the retriever
3. Ensure kwargs survive: from_objects(*args, sql_database=..., **kwargs) requires it as a keyword, not positional

Example fix

# before
mapping = SQLTableNodeMapping.from_objects(table_schema_objs)  # ValueError: Must provide sql_database

# after
from llama_index.core import SQLDatabase
sql_database = SQLDatabase(engine, include_tables=["city", "country"])
mapping = SQLTableNodeMapping.from_objects(table_schema_objs, sql_database=sql_database)

if sql_database is None:
    raise ValueError("SQLTableNodeMapping.from_objects requires a SQLDatabase; build one via SQLDatabase(engine)")
mapping = SQLTableNodeMapping.from_objects(table_schemas, sql_database=sql_database)

from llama_index.core import SQLDatabase
def is_valid_sql_database(db) -> bool:
    return isinstance(db, SQLDatabase)

try:
    mapping = SQLTableNodeMapping.from_objects(objs, sql_database=sql_database)
except ValueError as e:
    if "Must provide sql_database" in str(e):
        raise ValueError("construct SQLDatabase(engine) first and pass it as sql_database=") from e
    raise

When it happens

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

Common situations: Building a table-schema ObjectIndex for text-to-SQL (SQLTableRetriever) and forgetting the SQLDatabase argument; refactoring code that previously constructed SQLTableNodeMapping(sql_database) directly.

Related errors

• Invalid metric name: {metric}
• Cannot specify both similarity_fn and similarity_mode
• Unknown oversized document strategy: {strategy}
• Extractor loading requires a class_name
• num_nodes must be >= 1

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