docling-project/docling · error · ValueError

Unsupported numpy dtype for KServe v2 input: {tensor.dtype!s

Error message

Unsupported numpy dtype for KServe v2 input: {tensor.dtype!s}. Supported types: {list(NUMPY_KSERVE_V2_DATATYPES.keys())}

What it means

HTTP-path equivalent of the gRPC input dtype check: _tensor_kserve_dtype raises ValueError when a numpy input tensor's dtype is not in NUMPY_KSERVE_V2_DATATYPES while encoding the JSON request body. Only BOOL, UINT8/16/32/64, INT8/16/32/64, FP16/32/64 and object/BYTES are encodable.

Source

Thrown at docling/models/inference_engines/common/kserve_v2_http.py:37

from docling.models.inference_engines.common.kserve_v2_types import (
    KSERVE_V2_NUMPY_DATATYPES,
    NUMPY_KSERVE_V2_DATATYPES,
    KserveV2ModelMetadataResponse,
)
from docling.models.inference_engines.common.kserve_v2_utils import (
    decode_bytes_tensor,
    encode_bytes_tensor,
)

_log = logging.getLogger(__name__)
_INFERENCE_HEADER_CONTENT_LENGTH = "Inference-Header-Content-Length"


def _tensor_kserve_dtype(tensor: np.ndarray) -> str:
    kserve_dtype = NUMPY_KSERVE_V2_DATATYPES.get(tensor.dtype)
    if kserve_dtype is None:
        raise ValueError(
            f"Unsupported numpy dtype for KServe v2 input: {tensor.dtype!s}. "
            f"Supported types: {list(NUMPY_KSERVE_V2_DATATYPES.keys())}"
        )
    return kserve_dtype


def _encode_input_tensor(name: str, tensor: np.ndarray) -> Dict[str, Any]:
    kserve_dtype = _tensor_kserve_dtype(tensor)

    return {
        "name": name,
        "shape": list(tensor.shape),
        "datatype": kserve_dtype,
        "data": tensor.reshape(-1).tolist(),
    }


def _encode_binary_input_tensor(

View on GitHub (pinned to 61d76f1ff3)

Solutions

Convert string tensors to object dtype and numeric tensors to a supported width before calling infer (arr.astype(object) or arr.astype(np.float32))
Pre-validate: all(np.asarray(t).dtype in NUMPY_KSERVE_V2_DATATYPES for t in inputs.values())
Read the message - it prints the offending dtype and the exact supported set

Example fix

// before
inputs = {"input_str": np.array(["hello"])}  # '<U5'

// after
inputs = {"input_str": np.array(["hello"], dtype=object)}  # BYTES

Defensive patterns

Strategy: validation

Validate before calling

import numpy as np
from docling.models.inference_engines.common.kserve_v2_types import NUMPY_KSERVE_V2_DATATYPES

def validate_inputs(inputs: dict[str, np.ndarray]) -> None:
    for name, tensor in inputs.items():
        if np.asarray(tensor).dtype not in NUMPY_KSERVE_V2_DATATYPES:
            raise TypeError(f"Input {name!r} dtype not KServe v2 encodable")

Type guard

import numpy as np
from docling.models.inference_engines.common.kserve_v2_types import NUMPY_KSERVE_V2_DATATYPES

def is_encodable_tensor(tensor: np.ndarray) -> bool:
    return np.asarray(tensor).dtype in NUMPY_KSERVE_V2_DATATYPES

Try / catch

try:
    outputs = client.infer(inputs=inputs, output_names=[...])
except ValueError as e:
    if "Unsupported numpy dtype" in str(e):
        raise  # fix the caller's tensor dtypes; retrying unchanged will not help
    raise

Prevention

Construct string inputs with dtype=object
Centralize tensor construction in one factory that enforces supported dtypes
Add dtype asserts in tests so unsupported dtypes never reach infer

When it happens

Trigger: Posting infer() over HTTP with a '<U'-dtype string array, float128, complex, or datetime64 tensor; passing Python lists of mixed strings that np.asarray turns into '<U' dtype; object arrays whose per-element types cannot be encoded are fine, but the container dtype itself must be object.

Common situations: Sending string prompts/labels without dtype=object; porting a pipeline from a REST mock (which accepted anything) to the typed client; numpy version differences yielding unexpected result dtypes.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/99617196ab54b9ab. Report an issue: GitHub.