run-llama/llama_index · error · ValueError

ref_doc_id_column {ref_doc_id_column} not in table {table_na

Error message

ref_doc_id_column {ref_doc_id_column} not in table {table_name}

What it means

When ref_doc_id_column is supplied to SQLTableContext, the constructor validates that the named column actually exists in the target table (it inspects table.c for column names). A mismatch raises ValueError naming the bad column and table. This column is how SQL rows are linked back to their source documents, so it must be real.

Source

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

        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]:
        """Get col types map for schema."""
        return self._col_types_map

    def _get_schema_text(self) -> str:
        """Insert datapoint into index."""
        return self._sql_database.get_single_table_info(self._table_name)

    def _insert_datapoint(self, datapoint: StructDatapoint) -> None:
        """Insert datapoint into index."""

View on GitHub (pinned to afd0fef371)

Solutions

  1. Inspect the actual columns: print([c['name'] for c in sql_db.get_single_table_info(table_name)]) or list table.c, then pass the correct name.
  2. Add the missing column to the table (ALTER TABLE items ADD COLUMN source_id TEXT) if document linkage is intended.
  3. Drop ref_doc_id_column if you don't need row-to-document traceability.

Example fix

# before
context = SQLTableContext(
    sql_database=sql_db, table_name="items",
    ref_doc_id_column="source_id",  # column doesn't exist -> ValueError
)

# after (use the real column name)
context = SQLTableContext(
    sql_database=sql_db, table_name="items",
    ref_doc_id_column="ref_doc_id",
)
Defensive patterns

Strategy: validation

Validate before calling

table = sql_database.metadata_obj.tables[table_name]
col_names = {c.name for c in table.c}
if ref_doc_id_column and ref_doc_id_column not in col_names:
    raise ValueError(f"{ref_doc_id_column} not in {table_name}; columns: {sorted(col_names)}")

Prevention

When it happens

Trigger: Passing ref_doc_id_column='source_id' when the table has no such column; renaming a column in a migration without updating the index code; case/formatting mismatches between the passed name and the actual column name.

Common situations: Using SQLStructIndex.from_documents with ref_doc_id_column on a table created without that column; pointing at the wrong table name so column validation runs against a different schema; typos in column names.

Related errors

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