run-llama/llama_index · error · ValueError

context_dict must be provided. There is currently no table…

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.

Solutions

Use SQLContextContainerBuilder(sql_database, table_dict) and pass builder.get_sql_context_container() — it always yields a container with context_str set.
Or set at least one field explicitly: SQLContextContainer(context_str='table city_stats: ...') or SQLContextContainer(context_dict={'city_stats': 'city population table'}).
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())

Defensive patterns

Strategy: validation

Validate before calling

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)

Type guard

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 / catch

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

Prevention

Prefer SQLContextContainerBuilder.get_sql_context_container() over hand-built containers.
If building SQLContextContainer manually, always set context_str or a non-empty context_dict.
Omit the container entirely to let the index derive default schema context.

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

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

Appendix: 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)