cocoindex-io/cocoindex · error · ValueError

Unsupported NumPy dtype in NDArray

Error message

Unsupported NumPy dtype in NDArray: {dtype}. Supported dtypes: {cls._DTYPE_TO_KIND.keys()}

What it means

DtypeRegistry maps only np.float32, np.float64, and np.int64 to CocoIndex kinds. Any other concrete dtype (e.g. np.float16, np.int32, np.uint8, np.complex128) raises ValueError listing the supported dtypes.

Solutions

Convert the array to a supported dtype before indexing, e.g. arr.astype(np.float32)
Change the annotation to npt.NDArray[np.float32] (or float64/int64)
Upcast at the producer side so the stored/declared dtype matches the registry

Example fix

// before
embedding: npt.NDArray[np.float16]

// after
embedding: npt.NDArray[np.float32]  # or arr.astype(np.float32) before use

Defensive patterns

Strategy: validation

Validate before calling

SUPPORTED = {np.float32, np.float64, np.int64}
assert arr.dtype.type in SUPPORTED, f"{arr.dtype} not supported; astype first"

Type guard

def is_supported_dtype(a: np.ndarray) -> bool:
    return a.dtype.type in (np.float32, np.float64, np.int64)

Try / catch

try:
    kind = DtypeRegistry.validate_dtype_and_get_kind(dtype)
except ValueError:
    arr = arr.astype(np.float32)
    dtype = np.float32

Prevention

Convert model outputs (often float16) with astype(np.float32) before indexing
Keep the dtype in the annotation in sync with the produced array
Check cocoindex's supported-dtype list when adding new embedding pipelines

When it happens

Trigger: Annotating an NDArray-backed Vector with a supported-shaped but unsupported dtype such as npt.NDArray[np.float16] or npt.NDArray[np.int32] and having cocoindex analyze the type.

Common situations: Embedding pipelines producing float16 (common for ONNX/GPU models) or uint8 binary embeddings; integer IDs stored as int32; copying dtype from model output without conversion.

Related errors

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

Appendix: source

Thrown at python/cocoindex/_internal/datatype.py:89

    _DTYPE_TO_KIND: dict[Any, str] = {
        np.float32: "Float32",
        np.float64: "Float64",
        np.int64: "Int64",
    }

    @classmethod
    def validate_dtype_and_get_kind(cls, dtype: Any) -> str:
        """
        Validate that the given dtype is supported, and get its CocoIndex kind by dtype.
        """
        if dtype is Any:
            raise TypeError(
                "NDArray for Vector must use a concrete numpy dtype, got `Any`."
            )
        kind = cls._DTYPE_TO_KIND.get(dtype)
        if kind is None:
            raise ValueError(
                f"Unsupported NumPy dtype in NDArray: {dtype}. "
                f"Supported dtypes: {cls._DTYPE_TO_KIND.keys()}"
            )
        return kind


class AnyType(NamedTuple):
    """
    When the type annotation is missing or matches any type.
    """


class SequenceType(NamedTuple):
    """
    Any list type, e.g. list[T], Sequence[T], NDArray[T], etc.
    """

    elem_type: Any

View on GitHub (pinned to e84aa99b32)