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

A VectorSchemaProvider was supplied for a field whose Python type is not numpy.ndarray. Vector schemas are only meaningful for ndarray fields (mapped to array<float, N>), so CocoIndex rejects the combination, including the offending Python type in the message.

Source

Thrown at python/cocoindex/connectors/surrealdb/_target.py:294

    # Check direct leaf type mappings
    if base_type in _LEAF_TYPE_MAPPINGS:
        return _LEAF_TYPE_MAPPINGS[base_type]

    # NumPy ndarray: map to array<float, N>
    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(
            surreal_type=f"array<float, {vector_schema.size}>",
            encoder=_ndarray_encoder,
        )

    elif vector_schema is not None:
        raise ValueError(
            f"VectorSchemaProvider is only supported for NumPy ndarray type. "
            f"Got type: {python_type}"
        )

    # Complex types that need JSON encoding
    if isinstance(
        type_info.variant, (SequenceType, MappingType, RecordType, UnionType, AnyType)
    ):
        return _OBJECT_MAPPING

    # Default fallback
    return _OBJECT_MAPPING


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

View on GitHub (pinned to e84aa99b32)

Solutions

Remove the vector_schema from the non-ndarray field's column definition.
Or change the field type back to np.ndarray if vector semantics with a fixed dimension are intended.
If using lists, encode as a regular array/JSON column instead of a vector column.

Example fix

// before
{"embedding": (list[float], VectorSchemaProvider(size=768))}
// after
{"embedding": np.ndarray, "vector_schema": VectorSchemaProvider(size=768)}

Defensive patterns

Strategy: type-guard

Validate before calling

import numpy as np
if python_type is not np.ndarray and vector_schema is not None:
    raise ValueError("vector_schema only allowed for np.ndarray fields")

Type guard

def vector_schema_type_valid(python_type, vector_schema) -> bool:
    import numpy as np
    return vector_schema is None or python_type is np.ndarray

Try / catch

try:
    target = table_target(record_type, ...)
except ValueError as e:
    if "only supported for NumPy ndarray" in str(e):
        # drop vector_schema or switch the field to np.ndarray
        ...

Prevention

Only set vector_schema on fields annotated np.ndarray.
When changing a field type, audit attached column options like vector_schema.
Keep column option and field type definitions adjacent so mismatches are visible in review.

When it happens

Trigger: Declaring a SurrealDB column with vector_schema set for a field typed as list[float], list, or any non-ndarray type in the record type used by table_target/relation_target.

Common situations: Switching a field from np.ndarray to a plain list[float] (or a memoryview/bytes embedding) without removing the vector schema; copy-pasting column definitions between tables where one used ndarray.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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