cocoindex-io/cocoindex · error · ValueError

Column '{column}' not found in table schema: {list(self._tab

Error message

Column '{column}' not found in table schema: {list(self._table_schema.columns.keys())}

What it means

declare_vector_index builds a vector index over an existing declared column. Before creating the index spec it checks the column exists in the target's table schema; if not, it raises ValueError listing the available columns. This prevents creating an index that LanceDB would reject.

Source

Thrown at python/cocoindex/connectors/lancedb/_target.py:1334

        Declare a vector index on a column of this LanceDB table.

        Uses LanceDB's async ``create_index`` API with IVF-PQ or HNSW-PQ.

        Args:
            name: Logical index name (defaults to ``column``).
            column: Column to index.
            metric: Distance metric ("cosine", "l2", or "dot").
            index_type: Index algorithm: "ivf_pq" (IVF-PQ) or "hnsw_pq" (HNSW-PQ).
            num_partitions: (ivf_pq only) Number of IVF partitions.
            num_sub_vectors: (ivf_pq / hnsw_pq) Number of PQ sub-vectors.
            num_bits: (ivf_pq / hnsw_pq) Number of bits per PQ code.
            m: (hnsw_pq only) Maximum number of HNSW edges per node.
            ef_construction: (hnsw_pq only) Size of the HNSW candidate list during build.
        """
        if name is None:
            name = column
        if column not in self._table_schema.columns:
            raise ValueError(
                f"Column '{column}' not found in table schema: "
                f"{list(self._table_schema.columns.keys())}"
            )
        spec = _VectorIndexSpec(
            column=column,
            metric=metric,
            index_type=index_type,
            num_partitions=num_partitions,
            num_sub_vectors=num_sub_vectors,
            num_bits=num_bits,
            m=m,
            ef_construction=ef_construction,
        )
        att_provider = self._provider.attachment("vector_index")
        coco.declare_target_state(att_provider.target_state(name, spec))

    def declare_fts_index(
        self: "TableTarget[RowT]",

View on GitHub (pinned to e84aa99b32)

Solutions

Fix the column name to match one of the schema columns printed in the message
Declare the column in the table spec first, then declare the vector index on it
Verify you are calling declare_vector_index on the target whose schema actually contains that column

Example fix

// before
await target.declare_vector_index(column="embedding", metric="cosine")  # column is named 'vector'
// after
await target.declare_vector_index(column="vector", metric="cosine")

Defensive patterns

Strategy: validation

Validate before calling

available = target.table_schema.columns  # or the schema you declared
assert "embedding" in available, f"column missing; have {list(available)}"
await target.declare_vector_index(column="embedding", metric="cosine")

Type guard

def column_exists(schema, column: str) -> bool:
    return column in getattr(schema, "columns", {})

Try / catch

try:
    target.declare_vector_index(column=name, metric=metric)
except ValueError as e:
    if "not found in table schema" in str(e):
        raise KeyError(f"{name!r} not declared; available: {list(schema.columns)}") from e
    raise

Prevention

Declare the index immediately after the column in the same schema block
Use constants/shared names for column names instead of string literals in multiple places
Copy column names from the error's available-columns list to spot typos
Check whether you're holding the right target object before declaring indexes

When it happens

Trigger: Calling table_target.declare_vector_index(column=..., metric=...) with a column name that is not in the declared table schema (typo, renamed field, or indexing a column declared later or in a different target).

Common situations: Typos in the column name; renaming an embedding column (e.g. 'vector' -> 'embedding') without updating the index declaration; declaring the index on the wrong table target; copying example code with different column names.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/7f27e84486589e92. Report an issue: GitHub.