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

This ValueError is raised by _get_type_mapping when a VectorSchemaProvider is provided for a column whose Python type is not numpy.ndarray. Vector schema overrides only make sense for ndarray (vector) columns; applying one to any other type is a configuration contradiction, so the connector rejects it and names the offending type.

Source

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

        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


# ---------------------------------------------------------------------------
# ColumnDef
# ---------------------------------------------------------------------------


class ColumnDef(NamedTuple):

View on GitHub (pinned to e84aa99b32)

Solutions

  1. Remove the VectorSchemaProvider override for non-ndarray columns.
  2. Change the column's type to np.ndarray if it is genuinely a vector.
  3. Split the overrides dict per record type so overrides match each schema's fields.

Example fix

// before
column_overrides={"embedding": VectorSchemaProvider(size=384)}  # embedding: list[float]
// after
# either change the field to np.ndarray, or drop the override:
column_overrides={}
Defensive patterns

Strategy: type-guard

Validate before calling

import dataclasses, numpy as np
from cocoindex.resources import schema as res_schema
vector_cols = {f.name for f in dataclasses.fields(Record) if f.type is np.ndarray}
overrides = {k: v for k, v in overrides.items()
             if not isinstance(v, res_schema.VectorSchemaProvider) or k in vector_cols}

Type guard

def is_vector_column(record_type, name: str) -> bool:
    import dataclasses, numpy as np
    return any(f.name == name and f.type is np.ndarray
               for f in dataclasses.fields(record_type))

Try / catch

try:
    schema = await TableSchema.from_class(Record, column_overrides=overrides)
except ValueError as e:
    raise RuntimeError(f"column_overrides do not match record fields: {e}") from e

Prevention

When it happens

Trigger: Passing column_overrides={"<col>": VectorSchemaProvider(...)} for a column typed str, int, list[float], or any non-ndarray type in the record type.

Common situations: Refactoring a column from np.ndarray to list[float] while leaving the override in place; copy-pasting override dicts between schemas; a generic column_overrides map applied to multiple record types.

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/75644ec4921ccb36. Report an issue: GitHub.