run-llama/llama_index · error · TypeError

sample_rows_in_table_info must be an integer

Error message

sample_rows_in_table_info must be an integer

What it means

SQLWrapper validates that sample_rows_in_table_info (the number of example rows embedded in each table's context info for the LLM) is an int; passing anything else - a string like '3', a float, None - raises TypeError at construction time.

Source

Thrown at llama-index-core/llama_index/core/utilities/sql_wrapper.py:89

        self._include_tables = set(include_tables) if include_tables else set()
        if self._include_tables:
            missing_tables = self._include_tables - self._all_tables
            if missing_tables:
                raise ValueError(
                    f"include_tables {missing_tables} not found in database"
                )
        self._ignore_tables = set(ignore_tables) if ignore_tables else set()
        if self._ignore_tables:
            missing_tables = self._ignore_tables - self._all_tables
            if missing_tables:
                raise ValueError(
                    f"ignore_tables {missing_tables} not found in database"
                )
        usable_tables = self.get_usable_table_names()
        self._usable_tables = set(usable_tables) if usable_tables else self._all_tables

        if not isinstance(sample_rows_in_table_info, int):
            raise TypeError("sample_rows_in_table_info must be an integer")

        self._sample_rows_in_table_info = sample_rows_in_table_info
        self._indexes_in_table_info = indexes_in_table_info

        self._custom_table_info = custom_table_info
        if self._custom_table_info:
            if not isinstance(self._custom_table_info, dict):
                raise TypeError(
                    "table_info must be a dictionary with table names as keys and the "
                    "desired table info as values"
                )
            # only keep the tables that are also present in the database
            intersection = set(self._custom_table_info).intersection(self._all_tables)
            self._custom_table_info = {
                table: info
                for table, info in self._custom_table_info.items()
                if table in intersection
            }

View on GitHub (pinned to afd0fef371)

Solutions

1. Convert explicitly at the boundary: sample_rows_in_table_info=int(value).
2. Add schema validation (pydantic settings) for config so numeric fields arrive typed.
3. If you want no sample rows, pass the int 0 rather than None.

Example fix

# before
 db = SQLDatabase(engine, sample_rows_in_table_info=os.environ['SAMPLE_ROWS'])  # '3' str

# after
 db = SQLDatabase(engine, sample_rows_in_table_info=int(os.environ['SAMPLE_ROWS']))

def coerce_sample_rows(value) -> int:
    if value is None:
        return 3  # library default
    n = int(value)
    if n < 0:
        raise ValueError('sample_rows_in_table_info must be >= 0')
    return n

# usage: SQLDatabase(engine, sample_rows_in_table_info=coerce_sample_rows(cfg['sample_rows']))

def is_valid_sample_rows(value) -> bool:
    return isinstance(value, int) and not isinstance(value, bool) and value >= 0

try:
    db = SQLDatabase(engine, sample_rows_in_table_info=cfg['sample_rows'])
except TypeError as e:
    if 'must be an integer' in str(e):
        db = SQLDatabase(engine, sample_rows_in_table_info=int(cfg['sample_rows']))
    else:
        raise

When it happens

Trigger: SQLDatabase(engine, sample_rows_in_table_info='3') from unconverted config/env values; passing 3.0 (float) or a numpy integer on some paths; templated YAML that yields strings.

Common situations: Loading SQLDatabase settings from environment variables or YAML where everything is a string; notebook code passing a slider/widget value without int() conversion.

Related errors

• table_info must be a dictionary with table names as keys and
• Must provide sql_database
• No async database URI or engine provided, cannot initialize
• embed_model must start with str 'local' or of type BaseEmbed
• Must pass in cohere api key or specify via COHERE_API_KEY en

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