run-llama/llama_index · error · ValueError

Invalid context table names: {context_keys - set(self.sql_da

Error message

Invalid context table names: {context_keys - set(self.sql_database.get_usable_table_names())}

What it means

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.

Source

Thrown at llama-index-core/llama_index/core/indices/struct_store/container_builder.py:52

    """

    def __init__(
        self,
        sql_database: SQLDatabase,
        context_dict: Optional[Dict[str, str]] = None,
        context_str: Optional[str] = None,
    ):
        """Initialize params."""
        self.sql_database = sql_database

        # if context_dict provided, validate that all keys are valid table names
        if context_dict is not None:
            # validate context_dict keys are valid table names
            context_keys = set(context_dict.keys())
            if not context_keys.issubset(
                set(self.sql_database.get_usable_table_names())
            ):
                raise ValueError(
                    "Invalid context table names: "
                    f"{context_keys - set(self.sql_database.get_usable_table_names())}"
                )
        self.context_dict = context_dict or {}
        # build full context from sql_database
        self.full_context_dict = self._build_context_from_sql_database(
            self.sql_database, current_context=self.context_dict
        )
        self.context_str = context_str

    @classmethod
    def from_documents(
        cls,
        documents_dict: Dict[str, List[BaseNode]],
        sql_database: SQLDatabase,
        **context_builder_kwargs: Any,
    ) -> "SQLContextContainerBuilder":
        """Build context from documents."""

View on GitHub (pinned to afd0fef371)

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

Example fix

# before
sql_db = SQLDatabase(engine, include_tables=['users'])
builder = SQLContextContainerBuilder(sql_db, context_dict={'user': '...'})  # 'user' not usable

# after
sql_db = SQLDatabase(engine, include_tables=['users'])
builder = SQLContextContainerBuilder(sql_db, context_dict={'users': '...'})

Defensive patterns

Strategy: validation

Validate before calling

usable = set(sql_database.get_usable_table_names())
invalid = set(context_dict) - usable
if invalid:
    raise ValueError(f'unknown tables {invalid}; usable: {sorted(usable)}')
builder = SQLContextContainerBuilder(sql_database, context_dict=context_dict)

Type guard

def context_keys_are_valid(context_dict: dict, sql_database) -> bool:
    return set(context_dict).issubset(set(sql_database.get_usable_table_names()))

Try / catch

try:
    builder = SQLContextContainerBuilder(sql_database, context_dict=context_dict)
except ValueError as e:
    if 'Invalid context table names' in str(e):
        usable = set(sql_database.get_usable_table_names())
        context_dict = {k: v for k, v in context_dict.items() if k in usable}
        builder = SQLContextContainerBuilder(sql_database, context_dict=context_dict)
    else:
        raise

Prevention

Derive context_dict keys from get_usable_table_names() instead of hardcoding them
Add a startup assert comparing configured table names against live schema

When it happens

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

Common situations: 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.

Related errors

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