cocoindex-io/cocoindex · error · ValueError

VectorSchemaProvider is required for NumPy ndarray type.

Error message

VectorSchemaProvider is required for NumPy ndarray type.

What it means

NumPy ndarray columns are stored as sqlite-vec vectors, whose fixed dimension can only be known from an attached VectorSchemaProvider. Without one, `_get_type_mapping` cannot determine the SQL type `float[N]` or the serializer, so it raises. This keeps column schema derivation deterministic from the record type.

Source

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

    Use `SqliteType` annotation with `typing.Annotated` to override the default.
    """
    type_info = analyze_type_info(python_type)

    # Check for SqliteType annotation override
    for annotation in type_info.annotations:
        if isinstance(annotation, SqliteType):
            return _TypeMapping(annotation.sqlite_type, annotation.encoder)

    base_type = type_info.base_type

    # Check direct leaf type mappings
    if base_type in _LEAF_TYPE_MAPPINGS:
        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(

View on GitHub (pinned to e84aa99b32)

Solutions

1. Attach a VectorSchemaProvider to the ndarray field specifying the vector dimension (e.g. via typing.Annotated).
2. Alternatively change the field type to a fixed-size type the connector maps without a schema.
3. Ensure the provider's size matches your embedding model's output dimension.

Example fix

// before
embedding: np.ndarray
// after
embedding: Annotated[np.ndarray, VectorSchemaProvider(size=384)]

import typing
from cocoindex.connectors.sqlite import VectorSchemaProvider

for name, f in Row.__dataclass_fields__.items():
    if f.type is np.ndarray or "ndarray" in str(f.type):
        has_schema = any(isinstance(m, VectorSchemaProvider) for m in typing.get_args(f.type)[1:])
        assert has_schema, f"Field {name} needs VectorSchemaProvider"

try:
    target = sqlite.table_target(record_type=Row, ...)
except ValueError as e:
    if "VectorSchemaProvider is required" in str(e):
        raise ConfigError("Add Annotated[np.ndarray, VectorSchemaProvider(size=N)] to the embedding field") from e
    raise

When it happens

Trigger: Defining a dataclass/NamedTuple record type with an `np.ndarray` field and calling `table_target`/`from_class` without providing a vector schema (no VectorSchemaProvider annotation/metadata for that field).

Common situations: Embedding pipelines where the record field is typed `np.ndarray` but the developer forgot to attach the VectorSchemaProvider with the embedding dimension.

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

• VectorSchemaProvider is required for NumPy ndarray type.
• VectorSchemaProvider is required for NumPy ndarray type.
• Table '{table_name}' has vector column(s) {vector_cols}, but
• VectorSchemaProvider is required for NumPy ndarray type.
• Invalid vector dimension: {vector_schema.size}

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