{"record":{"id":"8293fac751406887","repo":"docling-project/docling","slug":"unsupported-kserve-request-parameter-integer-range","errorCode":null,"errorMessage":"Unsupported KServe request parameter integer range for gRPC: key={key}, value={int_value}","messagePattern":"Unsupported KServe request parameter integer range for gRPC: key=(.+?), value=(.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/common/kserve_v2_grpc.py","lineNumber":95,"sourceCode":"    key: str,\n    value: Any,\n) -> None:\n    parameter = parameter_map[key]\n    if isinstance(value, bool | np.bool_):\n        parameter.bool_param = bool(value)\n        return\n    if isinstance(value, int | np.integer):\n        int_value = int(value)\n        if int_value < 0:\n            parameter.int64_param = int_value\n            return\n        if int_value <= (2**63 - 1):\n            parameter.int64_param = int_value\n            return\n        if int_value <= (2**64 - 1):\n            parameter.uint64_param = int_value\n            return\n        raise ValueError(\n            \"Unsupported KServe request parameter integer range for gRPC: \"\n            f\"key={key}, value={int_value}\"\n        )\n    if isinstance(value, float | np.floating):\n        parameter.double_param = float(value)\n        return\n    if isinstance(value, str):\n        parameter.string_param = value\n        return\n    raise ValueError(\n        \"Unsupported KServe request parameter type for gRPC: \"\n        f\"key={key}, type={type(value)}. Supported: bool, int, float, str.\"\n    )\n\n\ndef _encode_contents(tensor: np.ndarray, contents: Any) -> None:\n    \"\"\"Populate an InferTensorContents message from a numpy array (non-binary path).\"\"\"\n    flat = tensor.flatten()","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/common/kserve_v2_grpc.py#L77-L113","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"# before\nparams = {'seed': 2**70}  # exceeds uint64 -> ValueError\n\n# after\nparams = {'seed': str(2**70)}  # or recompute to fit: seed & (2**64 - 1)","handlingStrategy":"validation","validationCode":"UINT64_MAX = 2**64 - 1\nparams = {k: (str(v) if isinstance(v, int) and v > UINT64_MAX else v) for k, v in params.items()}","typeGuard":"def fits_grpc_int(value) -> bool:\n    return isinstance(value, int) and -(2**63) <= value <= 2**64 - 1","tryCatchPattern":null,"preventionTips":["Whitelist and clamp inference parameters before dispatch.","Send arbitrary-precision values as strings.","Log parameter values on failure to spot overflow bugs quickly."],"tags":["kserve","grpc","validation","parameters","overflow"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}