cocoindex-io/cocoindex · error · ValueError

VectorSchemaProvider is required for NumPy ndarray type.

Error message

VectorSchemaProvider is required for NumPy ndarray type.

What it means

This ValueError is raised by _get_type_mapping when a column's Python type is numpy.ndarray but no VectorSchemaProvider (vector schema) was supplied in column_overrides. The connector needs the vector size (and metadata) to map the ndarray to Neo4j's LIST<FLOAT> type. It cannot infer the dimension from the type annotation alone, so it fails fast.

Source

Thrown at python/cocoindex/connectors/neo4j/_target.py:313

async def _get_type_mapping(
    python_type: Any, *, vector_schema: res_schema.VectorSchema | None = None
) -> _TypeMapping:
    type_info = analyze_type_info(python_type)

    for annotation in type_info.annotations:
        if isinstance(annotation, Neo4jType):
            return _TypeMapping(annotation.neo4j_type, annotation.encoder)

    base_type = type_info.base_type

    if base_type in _LEAF_TYPE_MAPPINGS:
        return _LEAF_TYPE_MAPPINGS[base_type]

    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}")
        return _TypeMapping(
            neo4j_type="LIST<FLOAT>",
            encoder=_ndarray_to_list,
        )
    elif vector_schema is not None:
        raise ValueError(
            "VectorSchemaProvider is only supported for NumPy ndarray type. "
            f"Got type: {python_type}"
        )

    if isinstance(type_info.variant, (SequenceType,)):
        return _ARRAY_MAPPING
    if isinstance(type_info.variant, (MappingType, RecordType, UnionType, AnyType)):
        return _OBJECT_MAPPING

    return _OBJECT_MAPPING

View on GitHub (pinned to e84aa99b32)

Solutions

1. Pass column_overrides={"<field>": res_schema.VectorSchemaProvider(size=<dim>)} when building the TableSchema.
2. Annotate the field appropriately or provide the vector schema via the schema-building API.
3. If the column should not be a vector, change the type or drop the column.

Example fix

// before
TableSchema.from_class(DocRecord)  # DocRecord.embedding: np.ndarray
// after
TableSchema.from_class(DocRecord, column_overrides={"embedding": VectorSchemaProvider(size=768)})

import dataclasses, numpy as np
from cocoindex.resources import schema as res_schema
overrides = {
    f.name: res_schema.VectorSchemaProvider(size=EMBED_DIM)
    for f in dataclasses.fields(Record)
    if f.type is np.ndarray
}

try:
    schema = await TableSchema.from_class(Record, column_overrides=overrides)
except ValueError as e:
    raise RuntimeError("every ndarray column needs a VectorSchemaProvider override") from e

When it happens

Trigger: Building a TableSchema from a record type with an np.ndarray field (embedding column) without passing a VectorSchemaProvider for that column in column_overrides.

Common situations: Defining a dataclass with an `embedding: np.ndarray` field and forgetting the override; refactoring from list[float] to ndarray without adding the vector schema; auto-generated schemas where column_overrides was not populated.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• VectorSchemaProvider is required for NumPy ndarray type.
• VectorSchemaProvider is only supported for NumPy ndarray typ
• VectorSchemaProvider is required for NumPy ndarray type.
• 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/03b004753f49bc86. Report an issue: GitHub.