cocoindex-io/cocoindex · error · ValueError

Unsupported NumPy dtype in NDArray: {dtype}. Supported dtype

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.

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)

Solutions

1. Convert the array to a supported dtype before indexing, e.g. arr.astype(np.float32)
2. Change the annotation to npt.NDArray[np.float32] (or float64/int64)
3. 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

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

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

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

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

• Invalid dtype specification: {dtype_spec}
• NDArray for Vector must use a concrete numpy dtype, got `Any
• Unsupported dense vector dtype {dtype!r}; zvec dense vectors
• VectorSpecProvider is required for NumPy ndarray type.
• Turbopuffer vectors only support float32 or float16, got {dt

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