cocoindex-io/cocoindex · error · ValueError

Vector column {name!r} requires a VectorSchema (provide it v

Error message

Vector column {name!r} requires a VectorSchema (provide it via an Annotated NDArray or column_overrides).

What it means

An ndarray-typed column without an associated VectorSchema annotation cannot be mapped to a zvec dense vector column. _resolve_column raises ValueError telling you to supply VectorSchema via an Annotated NDArray or column_overrides.

Source

Thrown at python/cocoindex/connectors/zvec/_target.py:393

            data_type=_dense_vector_data_type(vector_schema.dtype),
            nullable=type_info.nullable,
            dimension=vector_schema.size,
            metric=vd.metric,
            quantize=vd.quantize,
        )

    # Sparse vector: explicitly marked via ZvecVectorDef(sparse=True).
    if vector_def is not None and vector_def.sparse:
        return _Column(
            name=name,
            kind="sparse",
            data_type=_zvec.DataType.SPARSE_VECTOR_FP32,
            nullable=type_info.nullable,
            metric=vector_def.metric,
        )

    if type_info.base_type is np.ndarray:
        raise ValueError(
            f"Vector column {name!r} requires a VectorSchema (provide it via an "
            "Annotated NDArray or column_overrides)."
        )

    # Full-text field: str marked with ZvecFtsType.
    if fts_type is not None:
        if zvec_type is not None:
            raise ValueError(
                f"Column {name!r} cannot combine ZvecFtsType with ZvecType."
            )
        if type_info.base_type is not str:
            raise ValueError(
                f"ZvecFtsType on column {name!r} requires a str field, got "
                f"{type_info.base_type!r}."
            )
        return _Column(
            name=name,
            kind="fts",

View on GitHub (pinned to e84aa99b32)

Solutions

1. Annotate the column: Annotated[np.ndarray, VectorSchema(size=D)]
2. Or supply the VectorSchema through column_overrides for that column
3. Add the missing VectorSchema via column_overrides for that column

Example fix

// before
vec: np.ndarray
// after
vec: Annotated[np.ndarray, VectorSchema(size=384, vector_def=ZvecVectorDef())]

from typing import Annotated, get_type_hints
hints = get_type_hints(Row, include_extras=True)
for n, t in hints.items():
    if get_origin(t) is np.ndarray:
        assert any(isinstance(a, VectorSchema) for a in get_args(t)[1:]), f"{n} missing VectorSchema"

def has_vector_schema(annotation: object) -> bool:
    return get_origin(annotation) is Annotated and any(
        isinstance(m, VectorSchema) for m in get_args(annotation)[1:])

try:
    schema = ZvecCollection.from_class(Row)
except ValueError as e:
    if "requires a VectorSchema" in str(e):
        # fix the annotation or pass column_overrides={...}
        ...
    else:
        raise

When it happens

Trigger: Declaring a column as plain np.ndarray (or ndarray via column_overrides) without VectorSchema metadata when calling from_class.

Common situations: Forgetting the Annotated wrapper; passing a bare ndarray type in column_overrides without a vector schema; converting an existing schema where vector metadata was dropped.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid vector dimension for {name!r}: {vector_schema.size}
• Invalid vector dimension: {vector_schema.size}
• Invalid vector dimension: {vector_schema.size}
• Named-vectors dict is empty; declare at least one vector fie
• Invalid {kind}: {name!r}

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