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

`_get_type_mapping` only accepts a `VectorSchemaProvider` for columns annotated as `numpy.ndarray`. Supplying one for any other Python type (e.g. `list[float]`, `str`) is contradictory — the provider would never be used — so the library raises ValueError naming the offending type.

Source

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

        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


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


class ColumnDef(NamedTuple):

View on GitHub (pinned to e84aa99b32)

Solutions

Remove the `VectorSchemaProvider` from `column_overrides` for non-ndarray fields.
Change the field annotation to `np.ndarray` if you intended a vector column, keeping the provider.
If the field is `list[float]`, rely on the default array mapping instead of a vector provider.

Example fix

// before
column_overrides={"emb": VectorSchemaProvider(dimension=384)}  # field annotated list[float]
// after
# either annotate: emb: np.ndarray
# or drop the override:
column_overrides={}

Defensive patterns

Strategy: type-guard

Validate before calling

for name, provider in overrides.items():
    ann = typing.get_type_hints(Row)[name]
    if not (ann is np.ndarray) and isinstance(provider, res_schema.VectorSchemaProvider):
        raise ValueError(f"VectorSchemaProvider only valid for np.ndarray field {name!r}")

Type guard

def expects_vector_schema(ann: object) -> bool:
    return ann is np.ndarray

Try / catch

try:
    schema = await falkordb.TableSchema.from_class(Row, column_overrides=overrides)
except ValueError as e:
    if "only supported for NumPy ndarray" in str(e):
        logging.error("Remove vector overrides from non-ndarray fields: %s", e)
    raise

Prevention

Keep overrides minimal — one entry per ndarray vector field.
Annotate embedding fields as np.ndarray consistently across the codebase.
Type-check the overrides dict against the record's fields in tests.

When it happens

Trigger: Building a `TableSchema.from_class` where `column_overrides` maps a non-ndarray field (e.g. a `list[float]` embedding or a scalar field) to a `VectorSchemaProvider`.

Common situations: Migrating a schema from `list[float]` embeddings to ndarray without dropping the old override; copy-pasting a column_overrides dict where field names were renamed; applying a shared overrides dict 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/237e32c697de4a25. Report an issue: GitHub.