{"record":{"id":"2410f9ba273a08a3","repo":"run-llama/llama_index","slug":"invalid-context-table-names-context-keys-set-s","errorCode":null,"errorMessage":"Invalid context table names: {context_keys - set(self.sql_database.get_usable_table_names())}","messagePattern":"Invalid context table names: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/struct_store/container_builder.py","lineNumber":52,"sourceCode":"    \"\"\"\n\n    def __init__(\n        self,\n        sql_database: SQLDatabase,\n        context_dict: Optional[Dict[str, str]] = None,\n        context_str: Optional[str] = None,\n    ):\n        \"\"\"Initialize params.\"\"\"\n        self.sql_database = sql_database\n\n        # if context_dict provided, validate that all keys are valid table names\n        if context_dict is not None:\n            # validate context_dict keys are valid table names\n            context_keys = set(context_dict.keys())\n            if not context_keys.issubset(\n                set(self.sql_database.get_usable_table_names())\n            ):\n                raise ValueError(\n                    \"Invalid context table names: \"\n                    f\"{context_keys - set(self.sql_database.get_usable_table_names())}\"\n                )\n        self.context_dict = context_dict or {}\n        # build full context from sql_database\n        self.full_context_dict = self._build_context_from_sql_database(\n            self.sql_database, current_context=self.context_dict\n        )\n        self.context_str = context_str\n\n    @classmethod\n    def from_documents(\n        cls,\n        documents_dict: Dict[str, List[BaseNode]],\n        sql_database: SQLDatabase,\n        **context_builder_kwargs: Any,\n    ) -> \"SQLContextContainerBuilder\":\n        \"\"\"Build context from documents.\"\"\"","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/struct_store/container_builder.py#L34-L70","documentation":"SQLContextContainerBuilder validates that every key in the context_dict you pass is a usable table name in the provided SQLDatabase. Keys that are not returned by sql_database.get_usable_table_names() (including case mismatches or tables excluded via include_tables/ignore_tables) are reported in the error set.","triggerScenarios":"Constructing SQLContextContainerBuilder(sql_database, context_dict={'user_accts': '...'}) when the table is actually named 'user_accounts', is in another schema, or was excluded when the SQLDatabase was created with include_tables/ignore_tables.","commonSituations":"Table-name casing differences (Postgres lowercases unquoted identifiers); passing context for tables from a different schema not in the engine's search path; context_dict keys copied from an outdated schema; SQLDatabase built with include_tables that omits the referenced table.","solutions":["Print sorted(sql_database.get_usable_table_names()) and rename your context_dict keys to match exactly","If the table should be visible, rebuild SQLDatabase(engine, include_tables=[...]) to include it, or drop ignore_tables entries","For schema-qualified access, ensure the schema is included in the engine/SQLDatabase so get_usable_table_names returns the plain name you use as key"],"exampleFix":"# before\nsql_db = SQLDatabase(engine, include_tables=['users'])\nbuilder = SQLContextContainerBuilder(sql_db, context_dict={'user': '...'})  # 'user' not usable\n\n# after\nsql_db = SQLDatabase(engine, include_tables=['users'])\nbuilder = SQLContextContainerBuilder(sql_db, context_dict={'users': '...'})","handlingStrategy":"validation","validationCode":"usable = set(sql_database.get_usable_table_names())\ninvalid = set(context_dict) - usable\nif invalid:\n    raise ValueError(f'unknown tables {invalid}; usable: {sorted(usable)}')\nbuilder = SQLContextContainerBuilder(sql_database, context_dict=context_dict)","typeGuard":"def context_keys_are_valid(context_dict: dict, sql_database) -> bool:\n    return set(context_dict).issubset(set(sql_database.get_usable_table_names()))","tryCatchPattern":"try:\n    builder = SQLContextContainerBuilder(sql_database, context_dict=context_dict)\nexcept ValueError as e:\n    if 'Invalid context table names' in str(e):\n        usable = set(sql_database.get_usable_table_names())\n        context_dict = {k: v for k, v in context_dict.items() if k in usable}\n        builder = SQLContextContainerBuilder(sql_database, context_dict=context_dict)\n    else:\n        raise","preventionTips":["Derive context_dict keys from get_usable_table_names() instead of hardcoding them","Add a startup assert comparing configured table names against live schema"],"tags":["llama-index","sql","schema-validation","context-container"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}