cocoindex-io/cocoindex · error · ValueError

VectorSpecProvider is only supported for NumPy ndarray type.

Error message

VectorSpecProvider is only supported for NumPy ndarray type. Got type: {python_type}

What it means

A VectorSchemaProvider (vector schema) is only meaningful for np.ndarray fields that map to pgvector types. Supplying one for any other column type is contradictory, so _get_type_mapping raises ValueError.

Source

Thrown at python/cocoindex/connectors/postgres/_target.py:298

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

    # NumPy ndarray: map to pgvector type bases; dimension is handled at the schema layer.
    if base_type is np.ndarray:
        if vector_schema is None:
            raise ValueError("VectorSpecProvider is required for NumPy ndarray type.")
        if vector_schema.size <= 0:
            raise ValueError(f"Invalid pgvector dimension: {vector_schema.size}")

        # Default to `vector` (float32/float64/int64/etc.). Use `halfvec` for float16.
        base = "halfvec" if vector_schema.dtype in (np.half, np.float16) else "vector"
        return _TypeMapping(
            pg_type=f"{base}({vector_schema.size})", encoder=_vector_encoder
        )

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

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

    # Default fallback
    return _JSONB_MAPPING


class ColumnDef(NamedTuple):
    """Definition of a table column."""

    type: str  # PostgreSQL type (e.g., "text", "bigint", "jsonb", "vector(384)")
    nullable: bool = True

View on GitHub (pinned to e84aa99b32)

Solutions

1. Remove the VectorSchemaProvider override for non-ndarray columns.
2. Use a PgType override for plain columns instead.
3. Keep VectorSchemaProvider only for np.ndarray-typed fields.

Example fix

// before
overrides = {"title": VectorSchemaProvider(size=10), "embedding": VectorSchemaProvider(size=768)}
// after
overrides = {"embedding": VectorSchemaProvider(size=768)}

import numpy as np, typing
hints = typing.get_type_hints(Row)
for name, ov in overrides.items():
    if isinstance(ov, VectorSchemaProvider):
        assert hints[name] is np.ndarray, f"VectorSchemaProvider only valid on ndarray field '{name}'"

def vector_overrides_only_on_ndarray(row_type: type, overrides: dict) -> bool:
    import typing, numpy as np
    hints = typing.get_type_hints(row_type)
    return all(
        hints.get(name) is np.ndarray
        for name, ov in overrides.items()
        if isinstance(ov, VectorSchemaProvider)
    )

try:
    target = await PgTableTarget.from_class(Row, primary_key=["id"], column_overrides=ov)
except ValueError as e:
    if "only supported for NumPy ndarray" in str(e):
        ov = {k: v for k, v in ov.items() if not isinstance(v, VectorSchemaProvider) or k == "embedding"}

When it happens

Trigger: Passing column_overrides={"title": VectorSchemaProvider(size=10)} in TableTarget.from_class where the 'title' field is a str (or any non-ndarray type).

Common situations: Copy-pasting the vector override entry for all columns; confusing VectorSchemaProvider with a plain PgType override.

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

• VectorSpecProvider is required for NumPy ndarray type.
• Invalid pgvector dimension: {vector_schema.size}
• LiveComponent classes cannot be used with use_mount(). Use m
• Context key '{key}': expected {t.__name__}, got {type(value)
• Settings.db_path must be provided

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