cocoindex-io/cocoindex · error · ValueError

VectorSchemaProvider is only supported for NumPy ndarray typ

Error message

VectorSchemaProvider is only supported for NumPy ndarray type. Got type: {python_type}

What it means

VectorSchemaProvider metadata is only meaningful on NumPy ndarray fields, where it defines the sqlite-vec vector dimension. Attaching it to a field of any other type is contradictory — there is no vector to size — so `_get_type_mapping` rejects it with this ValueError.

Source

Thrown at python/cocoindex/connectors/sqlite/_target.py:271

        return _LEAF_TYPE_MAPPINGS[base_type]

    # NumPy ndarray: serialize to sqlite-vec compatible format
    if base_type is np.ndarray:
        if vector_schema is None:
            raise ValueError("VectorSchemaProvider is required for NumPy ndarray type.")

        if vector_schema.size <= 0:
            raise ValueError(f"Invalid vector dimension: {vector_schema.size}")

        # sqlite-vec uses float[N] type (e.g., float[384])
        import sqlite_vec  # type: ignore

        return _TypeMapping(
            f"float[{vector_schema.size}]", sqlite_vec.serialize_float32
        )

    elif vector_schema is not None:
        raise ValueError(
            f"VectorSchemaProvider is only supported for NumPy ndarray type. Got type: {python_type}"
        )

    # Complex types that need JSON encoding
    if isinstance(
        type_info.variant, (SequenceType, MappingType, RecordType, UnionType, AnyType)
    ):
        return _JSON_MAPPING

    # Default fallback
    return _JSON_MAPPING


class ColumnDef(NamedTuple):
    """Definition of a table column."""

    type: str  # SQLite type (e.g., "TEXT", "INTEGER", "REAL", "BLOB")
    nullable: bool = True

View on GitHub (pinned to e84aa99b32)

Solutions

  1. Change the field type to np.ndarray to match the VectorSchemaProvider annotation.
  2. Or remove the VectorSchemaProvider annotation if the field genuinely isn't a vector.
  3. If lists must be stored as vectors, convert to np.ndarray in the function before declaring the row.

Example fix

// before
embedding: Annotated[list[float], VectorSchemaProvider(size=768)]
// after
embedding: Annotated[np.ndarray, VectorSchemaProvider(size=768)]
Defensive patterns

Strategy: type-guard

Validate before calling

import typing, numpy as np
from cocoindex.connectors.sqlite import VectorSchemaProvider

for name, f in Row.__dataclass_fields__.items():
    ann = typing.get_args(f.type)
    has_provider = any(isinstance(m, VectorSchemaProvider) for m in ann[1:])
    if has_provider and ann[0] is not np.ndarray:
        raise TypeError(f"VectorSchemaProvider on non-ndarray field {name}: {ann[0]}")

Type guard

def provider_matches_type(annotation: object) -> bool:
    import typing, numpy as np
    args = typing.get_args(annotation)
    base = args[0] if args else annotation
    has_provider = any(isinstance(m, VectorSchemaProvider) for m in args[1:])
    return not has_provider or base is np.ndarray

Try / catch

try:
    target = sqlite.table_target(record_type=Row, ...)
except ValueError as e:
    if "only supported for NumPy ndarray" in str(e):
        raise ConfigError("Use np.ndarray as the field type together with VectorSchemaProvider") from e
    raise

Prevention

When it happens

Trigger: Declaring e.g. `Annotated[list[float], VectorSchemaProvider(size=768)]` or annotating a str/int field with VectorSchemaProvider, then building the target via `table_target`/`from_class`.

Common situations: Migrating from a list-of-floats embedding representation to ndarray (or vice versa) and leaving the old annotation in place; copying an annotated field template without changing the type.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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