{"record":{"id":"357b1416460930c4","repo":"run-llama/llama_index","slug":"ref-doc-id-column-ref-doc-id-column-not-in-table","errorCode":null,"errorMessage":"ref_doc_id_column {ref_doc_id_column} not in table {table_name}","messagePattern":"ref_doc_id_column (.+?) not in table (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/common/struct_store/sql.py","lineNumber":43,"sourceCode":"        table_name: Optional[str] = None,\n        table: Optional[Table] = None,\n        ref_doc_id_column: Optional[str] = None,\n    ) -> None:\n        \"\"\"Initialize params.\"\"\"\n        super().__init__(llm, schema_extract_prompt, output_parser)\n        self._sql_database = sql_database\n        # currently the user must specify a table info\n        if table_name is None and table is None:\n            raise ValueError(\"table_name must be specified\")\n        self._table_name = table_name or cast(Table, table).name\n        if table is None:\n            table_name = cast(str, table_name)\n            table = self._sql_database.metadata_obj.tables[table_name]\n        # if ref_doc_id_column is specified, then we need to check that\n        # it is a valid column in the table\n        col_names = [c.name for c in table.c]\n        if ref_doc_id_column is not None and ref_doc_id_column not in col_names:\n            raise ValueError(\n                f\"ref_doc_id_column {ref_doc_id_column} not in table {table_name}\"\n            )\n        self.ref_doc_id_column = ref_doc_id_column\n        # then store python types of each column\n        self._col_types_map: Dict[str, type] = {\n            c.name: table.c[c.name].type.python_type for c in table.c\n        }\n\n    def _get_col_types_map(self) -> Dict[str, type]:\n        \"\"\"Get col types map for schema.\"\"\"\n        return self._col_types_map\n\n    def _get_schema_text(self) -> str:\n        \"\"\"Insert datapoint into index.\"\"\"\n        return self._sql_database.get_single_table_info(self._table_name)\n\n    def _insert_datapoint(self, datapoint: StructDatapoint) -> None:\n        \"\"\"Insert datapoint into index.\"\"\"","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/common/struct_store/sql.py#L25-L61","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Add the missing column to the table (ALTER TABLE items ADD COLUMN source_id TEXT) if document linkage is intended.","Drop ref_doc_id_column if you don't need row-to-document traceability."],"exampleFix":"# before\ncontext = SQLTableContext(\n    sql_database=sql_db, table_name=\"items\",\n    ref_doc_id_column=\"source_id\",  # column doesn't exist -> ValueError\n)\n\n# after (use the real column name)\ncontext = SQLTableContext(\n    sql_database=sql_db, table_name=\"items\",\n    ref_doc_id_column=\"ref_doc_id\",\n)","handlingStrategy":"validation","validationCode":"table = sql_database.metadata_obj.tables[table_name]\ncol_names = {c.name for c in table.c}\nif ref_doc_id_column and ref_doc_id_column not in col_names:\n    raise ValueError(f\"{ref_doc_id_column} not in {table_name}; columns: {sorted(col_names)}\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate column names against sql_database.get_table_columns(table_name) before index construction.","Keep schema migrations and index configs in the same change set."],"tags":["sql","validation","schema-mismatch","table-context"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}