VectorSchemaProvider is required for NumPy ndarray type.

Error message

VectorSchemaProvider is required for NumPy ndarray type.

What it means

In `_get_type_mapping`, a `numpy.ndarray` column requires an explicit vector schema to know the FalkorDB vector type (`vector<float32, N>`) and dimension. If no `VectorSchemaProvider` override was supplied (via `column_overrides`), the library raises ValueError because the dimension cannot be inferred from the ndarray annotation alone.

Source

Thrown at python/cocoindex/connectors/falkordb/_target.py:274


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, FalkorType):
            return _TypeMapping(annotation.falkor_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(
            falkor_type=f"vector<float32, {vector_schema.size}>",
            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

Add a `VectorSchemaProvider` for the ndarray column in `column_overrides`, e.g. `column_overrides={"embedding": res_schema.VectorSchemaProvider(dimension=768)}`.
Alternatively annotate the field with a fixed-size typed form if supported instead of bare `np.ndarray`.
Check which column triggered it by comparing record fields against your overrides dict.

Example fix

// before
await falkordb.TableSchema.from_class(Record, primary_key="id")
// after
await falkordb.TableSchema.from_class(Record, primary_key="id", column_overrides={"embedding": res_schema.VectorSchemaProvider(dimension=384)})

Defensive patterns

Strategy: validation

Validate before calling

from cocoindex.resources import schema as res_schema
overrides = {"embedding": res_schema.VectorSchemaProvider(dimension=384)}
# ensure every np.ndarray field has an override before from_class
for f in dataclasses.fields(Row):
    if f.type is "np.ndarray" or f.type.endswith("ndarray"):
        assert f.name in overrides

Type guard

def is_ndarray_field(ann: object) -> bool:
    return ann is np.ndarray or getattr(ann, "__origin__", None) is np.ndarray

Try / catch

try:
    schema = await falkordb.TableSchema.from_class(Row, column_overrides=overrides)
except ValueError as e:
    if "VectorSchemaProvider is required" in str(e):
        logging.error("Add VectorSchemaProvider for ndarray fields: %s", e)
    raise

Prevention

Keep a single overrides dict co-located with the record definition.
Never annotate vector fields as bare np.ndarray without a matching override.
Add a unit test that builds all schemas at import time to fail fast.

When it happens

Trigger: Calling `TableSchema.from_class` (which calls `_columns_from_record_type` -> `_get_type_mapping`) on a record type whose field is annotated `np.ndarray` without passing a `VectorSchemaProvider` for that column in `column_overrides`.

Common situations: Defining a dataclass row with an `np.ndarray` embedding field and forgetting the column override; assuming the library infers dimension from a default value; copying a schema example that had vector metadata removed.

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

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