cocoindex-io/cocoindex · error · ValueError

VectorSchemaProvider is required for NumPy ndarray type.

Error message

VectorSchemaProvider is required for NumPy ndarray type.

What it means

When mapping a record's Python types to SurrealDB column types, a field of type numpy.ndarray requires a VectorSchemaProvider so CocoIndex knows the vector dimension N for the array<float, N> SurrealDB type. Without it the dimension is unknown and the mapping fails.

Source

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

    Use ``SurrealType`` annotation with ``typing.Annotated`` to override.
    """
    type_info = analyze_type_info(python_type)

    # Check for SurrealType annotation override
    for annotation in type_info.annotations:
        if isinstance(annotation, SurrealType):
            return _TypeMapping(annotation.surreal_type, annotation.encoder)

    base_type = type_info.base_type

    # 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)
    ):

View on GitHub (pinned to e84aa99b32)

Solutions

1. Attach a VectorSchemaProvider specifying the vector size/dimension to the ndarray field's column definition.
2. Alternatively change the field type to a typed sequence (e.g. list[float]) with a fixed length if vector semantics are not needed.
3. Verify the record type annotation is actually np.ndarray for that field and that the schema builder maps it to the provider.

Example fix

// before
columns = {"embedding": np.ndarray}
// after
columns = {"embedding": VectorSchemaProvider(size=768, dtype=np.float32)}

if any(isinstance(t, np.ndarray) for t in record_type_fields.values()) and not vector_schemas:
    raise ValueError("ndarray fields require a VectorSchemaProvider")

def ndarray_fields_have_vector_schema(fields, schemas) -> bool:
    import numpy as np
    return all(
        t is not np.ndarray or name in schemas
        for name, t in fields.items()
    )

try:
    target = table_target(record_type, ...)
except ValueError as e:
    if "VectorSchemaProvider is required" in str(e):
        # add vector_schema to the ndarray column and rebuild the target
        ...

When it happens

Trigger: Declaring a SurrealDB table_target/relation_target whose record type includes an np.ndarray field but passing no vector_schema for that column in _columns_from_record_type.

Common situations: Embedding vectors stored as numpy arrays without attaching a VectorSchemaProvider (with size and dimension) to the column definition; migrating a schema from another connector where vectors were typed differently.

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

• VectorSchemaProvider is required for NumPy ndarray type.
• VectorSchemaProvider is required for NumPy ndarray type.
• VectorSchemaProvider is required for NumPy ndarray type.
• VectorSchemaProvider is only supported for NumPy ndarray typ
• Invalid vector dimension: {vector_schema.size}

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