run-llama/llama_index · error · ValueError

context_dict must be provided. There is currently no table c

Error message

context_dict must be provided. There is currently no table context.

What it means

NLStructStoreQueryEngine._get_table_context() raises ValueError('context_dict must be provided...') when the SQLContextContainer has neither context_str nor context_dict. The engine builds the schema prompt by preferring container.context_str; if that is None it falls back to joining every value of context_dict, and if context_dict is also None there is no table context at all to put in the prompt, so it aborts rather than sending the LLM an empty schema.

Source

Thrown at llama-index-core/llama_index/core/indices/struct_store/sql_query.py:237

        # there's a ' in the value (e.g. "I'm")
        response = response.replace("\\'", "''")
        return response.strip()

    def _get_table_context(self, query_bundle: QueryBundle) -> str:
        """
        Get table context.

        Get tables schema + optional context as a single string. Taken from
        SQLContextContainer.

        """
        if self._sql_context_container.context_str is not None:
            tables_desc_str = self._sql_context_container.context_str
        else:
            table_desc_list = []
            context_dict = self._sql_context_container.context_dict
            if context_dict is None:
                raise ValueError(
                    "context_dict must be provided. There is currently no "
                    "table context."
                )
            for table_desc in context_dict.values():
                table_desc_list.append(table_desc)
            tables_desc_str = "\n\n".join(table_desc_list)

        return tables_desc_str

    def _run_with_sql_only_check(self, sql_query_str: str) -> Tuple[str, Dict]:
        """Don't run sql if sql_only is true, else continue with normal path."""
        if self._sql_only:
            metadata: Dict[str, Any] = {}
            raw_response_str = sql_query_str
        else:
            raw_response_str, metadata = self._sql_database.run_sql(sql_query_str)

        return raw_response_str, metadata

View on GitHub (pinned to afd0fef371)

Solutions

1. Use SQLContextContainerBuilder(sql_database, table_dict) and pass builder.get_sql_context_container() — it always yields a container with context_str set.
2. Or set at least one field explicitly: SQLContextContainer(context_str='table city_stats: ...') or SQLContextContainer(context_dict={'city_stats': 'city population table'}).
3. If you rely on the index default, simply omit context_container — the index builds a default container from the table schema.

Example fix

# before
container = SQLContextContainer()  # both fields None
engine = NLStructStoreQueryEngine(index, context_container=container)

# after
from llama_index.core.indices.struct_store import SQLContextContainerBuilder
builder = SQLContextContainerBuilder(sql_database, table_dict={"city_stats": "city population table"})
engine = NLStructStoreQueryEngine(index, context_container=builder.get_sql_context_container())

from llama_index.core.indices.struct_store.sql_query import SQLContextContainer

def has_table_context(c: SQLContextContainer) -> bool:
    return c.context_str is not None or bool(c.context_dict)

def is_usable_context_container(c) -> bool:
    return c is not None and (c.context_str is not None or bool(getattr(c, "context_dict", None)))

try:
    response = query_engine.query(q)
except ValueError as e:
    if "context_dict must be provided" in str(e):
        query_engine = NLStructStoreQueryEngine(
            index, context_container=SQLContextContainer(context_str=DEFAULT_SCHEMA_STR)
        )
        response = query_engine.query(q)
    else:
        raise

When it happens

Trigger: Constructing SQLContextContainer() with no arguments and passing it to NLStructStoreQueryEngine(index, context_container=...); manually building a container and setting only context_str=None fields; upgrading from older versions where the container auto-populated defaults.

Common situations: Hand-rolling SQLContextContainer instead of using SQLContextContainerBuilder; copy-pasting code that creates SQLContextContainer(context_dict={}) correctly but dropping the dict; partial initialization where context was assigned to a different variable than the one passed.

Related errors

• sql_database must be specified
• embeddings_cache must be of type BaseKVStore
• embeddings_cache must be defined
• Did not find {key}, please add an environment variable `{env
• Cannot add two handlers of the same type {type(new_handler)}

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