docling-project/docling · error · ValueError

Unsupported KServe request parameter integer range for gRPC:

Q: What causes "Unsupported KServe request parameter integer range for gRPC: key={key}, value={int_value}" in docling-project/docling?

Fix the parameter value — it is almost certainly a bug upstream (clamp or recompute the timestamp/hash).

Error message

Unsupported KServe request parameter integer range for gRPC: key={key}, value={int_value}

What it means

Raised as ValueError by _set_request_parameter when an integer inference parameter exceeds the representable gRPC KServe range. Values fit int64 (negative or <= 2^63-1) or uint64 (up to 2^64-1); anything above 2^64-1 cannot be encoded in the protobuf parameter.

Source

Thrown at docling/models/inference_engines/common/kserve_v2_grpc.py:95

    key: str,
    value: Any,
) -> None:
    parameter = parameter_map[key]
    if isinstance(value, bool | np.bool_):
        parameter.bool_param = bool(value)
        return
    if isinstance(value, int | np.integer):
        int_value = int(value)
        if int_value < 0:
            parameter.int64_param = int_value
            return
        if int_value <= (2**63 - 1):
            parameter.int64_param = int_value
            return
        if int_value <= (2**64 - 1):
            parameter.uint64_param = int_value
            return
        raise ValueError(
            "Unsupported KServe request parameter integer range for gRPC: "
            f"key={key}, value={int_value}"
        )
    if isinstance(value, float | np.floating):
        parameter.double_param = float(value)
        return
    if isinstance(value, str):
        parameter.string_param = value
        return
    raise ValueError(
        "Unsupported KServe request parameter type for gRPC: "
        f"key={key}, type={type(value)}. Supported: bool, int, float, str."
    )


def _encode_contents(tensor: np.ndarray, contents: Any) -> None:
    """Populate an InferTensorContents message from a numpy array (non-binary path)."""
    flat = tensor.flatten()

View on GitHub (pinned to 61d76f1ff3)

Solutions

Fix the parameter value — it is almost certainly a bug upstream (clamp or recompute the timestamp/hash).
If the value legitimately exceeds 64 bits, send it as a string parameter instead.
Validate parameter magnitudes before dispatch when parameters come from user input.

Example fix

# before
params = {'seed': 2**70}  # exceeds uint64 -> ValueError

# after
params = {'seed': str(2**70)}  # or recompute to fit: seed & (2**64 - 1)

Defensive patterns

Strategy: validation

Validate before calling

UINT64_MAX = 2**64 - 1
params = {k: (str(v) if isinstance(v, int) and v > UINT64_MAX else v) for k, v in params.items()}

Type guard

def fits_grpc_int(value) -> bool:
    return isinstance(value, int) and -(2**63) <= value <= 2**64 - 1

Prevention

Whitelist and clamp inference parameters before dispatch.
Send arbitrary-precision values as strings.
Log parameter values on failure to spot overflow bugs quickly.

When it happens

Trigger: Passing a request parameter larger than 2**64 - 1 in the parameters mapping of a KServe gRPC inference call (e.g. a mistakenly computed timestamp in nanoseconds, an unsigned overflow, or a sentinel value like 2**70).

Common situations: Programmatically generated parameters (timestamps, hashes, sizes) overflowing; numpy uint64 values from aggressive dtype promotion; copy-pasting HTTP-transport parameter dicts where huge ints were tolerated.

Related errors

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