run-llama/llama_index · error · ValueError

table_name must be specified

Error message

table_name must be specified

What it means

SQLTableContext must know which database table it extracts a schema for. It accepts either a table_name string or a SQLAlchemy Table object, and raises ValueError if both are None — there is no way to infer the target table. One of the two must identify the table.

Source

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

class SQLStructDatapointExtractor(BaseStructDatapointExtractor):
    """Extracts datapoints from a structured document for a SQL db."""

    def __init__(
        self,
        llm: LLM,
        schema_extract_prompt: BasePromptTemplate,
        output_parser: OUTPUT_PARSER_TYPE,
        sql_database: SQLDatabase,
        table_name: Optional[str] = None,
        table: Optional[Table] = None,
        ref_doc_id_column: Optional[str] = None,
    ) -> None:
        """Initialize params."""
        super().__init__(llm, schema_extract_prompt, output_parser)
        self._sql_database = sql_database
        # currently the user must specify a table info
        if table_name is None and table is None:
            raise ValueError("table_name must be specified")
        self._table_name = table_name or cast(Table, table).name
        if table is None:
            table_name = cast(str, table_name)
            table = self._sql_database.metadata_obj.tables[table_name]
        # if ref_doc_id_column is specified, then we need to check that
        # it is a valid column in the table
        col_names = [c.name for c in table.c]
        if ref_doc_id_column is not None and ref_doc_id_column not in col_names:
            raise ValueError(
                f"ref_doc_id_column {ref_doc_id_column} not in table {table_name}"
            )
        self.ref_doc_id_column = ref_doc_id_column
        # then store python types of each column
        self._col_types_map: Dict[str, type] = {
            c.name: table.c[c.name].type.python_type for c in table.c
        }

    def _get_col_types_map(self) -> Dict[str, type]:

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass table_name='my_table' explicitly to SQLTableContext.
2. Alternatively pass the SQLAlchemy Table object directly: table=sql_db.metadata_obj.tables['my_table'].
3. If iterating tables, assert the name is non-empty before constructing the context.

Example fix

# before
context = SQLTableContext(
    llm=llm, sql_database=sql_db,
    table_name=None, table=None,  # ValueError
)

# after
context = SQLTableContext(
    llm=llm, sql_database=sql_db,
    table_name="items",
)

if not table_name and table is None:
    raise ValueError("Pass table_name or table for the target table")

When it happens

Trigger: Constructing SQLTableContext(sql_database=db, table_name=None, table=None); building SQLStructIndex with a tables argument that fails to propagate a table name; calling the constructor with only keyword filters that don't map to table_name/table.

Common situations: Programmatically looping over tables and passing a falsy name by mistake; refactors where the positional order of (table_name, table) got swapped; relying on the index to auto-select a single table when several exist.

Related errors

• sql_database must be provided.
• ref_doc_id_column {ref_doc_id_column} not in table {table_na
• All agents must have a name in a multi-agent workflow
• All agents must have a description in a multi-agent workflow
• Initial state is not supported per-agent in AgentWorkflow

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