{"id":"897730154264969e","repo":"apache/kafka","slug":"about-value-value-does-not-fit-in-a-32-bit","errorCode":null,"errorMessage":"${about}: value ${value} does not fit in a 32-bit unsigned integer.","messagePattern":"(.+?): value (.+?) does not fit in a 32-bit unsigned integer\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/protocol/MessageUtil.java","lineNumber":107,"sourceCode":"            throw new RuntimeException(about + \": value \" + value +\n                \" does not fit in a 16-bit signed integer.\");\n        }\n        return (short) value;\n    }\n\n    public static int jsonNodeToUnsignedShort(JsonNode node, String about) {\n        int value = jsonNodeToInt(node, about);\n        if (value < 0 || value > UNSIGNED_SHORT_MAX) {\n            throw new RuntimeException(about + \": value \" + value +\n                \" does not fit in a 16-bit unsigned integer.\");\n        }\n        return value;\n    }\n\n    public static long jsonNodeToUnsignedInt(JsonNode node, String about) {\n        long value = jsonNodeToLong(node, about);\n        if (value < 0 || value > UNSIGNED_INT_MAX) {\n            throw new RuntimeException(about + \": value \" + value +\n                    \" does not fit in a 32-bit unsigned integer.\");\n        }\n        return value;\n    }\n\n    public static int jsonNodeToInt(JsonNode node, String about) {\n        if (node.isInt()) {\n            return node.asInt();\n        }\n        if (node.isTextual()) {\n            throw new NumberFormatException(about + \": expected an integer or \" +\n                \"string type, but got \" + node.getNodeType());\n        }\n        String text = node.asText();\n        if (text.startsWith(\"0x\")) {\n            try {\n                return Integer.parseInt(text.substring(2), 16);\n            } catch (NumberFormatException e) {","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/protocol/MessageUtil.java#L89-L125","documentation":"Thrown by MessageUtil.jsonNodeToUnsignedInt when a JSON value parses as a long but falls outside the unsigned 32-bit range [0, 4294967295]. Kafka's protocol schema declares some fields as uint32 (e.g. sizes, rates, certain ms durations) and these cannot carry negative values or values >= 2^32. The check rejects both underflow and overflow after Jackson has already accepted the number as a long.","triggerScenarios":"A JSON document is fed into a generated Message.fromJson / JSON deserializer for a uint32 protocol field. The JSON number is negative (e.g. -1) or greater than 4294967295L, so the range check at MessageUtil.java:107 throws RuntimeException. Common with producer_byte_rate / consumer_byte_rate quota values, throttle_time_ms overrides, or any hand-written JSON for AlterClientQuotas / DescribeClientQuotas requests.","commonSituations":"Setting a mutation quota or byte-rate to a value like 5000000000 that exceeds 2^32-1; using a negative sentinel like -1 intending 'unlimited' on a uint32 field; copying a value from a 64-bit config (long) into a uint32 protocol field during a broker version upgrade that narrowed the type; passing JSON to kafka-configs/AlterClientQuotas tooling with a typo in magnitude.","solutions":["Inspect the 'about' prefix in the thrown message — it names the specific field that overflowed.","Reduce the value to fit within [0, 4294967295]; for 'unlimited' semantics use the absence of the entry or the value 0 / -2 as documented for the specific field (some Kafka quota removals use -1 in the entry entity only, not in the value).","Regenerate/verify the JSON with a JSON validator and re-submit the request.","If you genuinely need 64-bit range, check whether the field is supposed to be uint64/long in the message spec — if so, you are calling the wrong accessor (jsonNodeToUnsignedInt instead of jsonNodeToLong)."],"exampleFix":"// before\n{\"entity\": {\"client-id\": 'app-1'}, \"quotas\": [{\"key\": \"producer_byte_rate\", \"value\": 6000000000}]}\n// after  (cap under 2^32-1)\n{\"entity\": {\"client-id\": 'app-1'}, \"quotas\": [{\"key\": \"producer_byte_rate\", \"value\": 1000000000}]}","handlingStrategy":"validation","validationCode":"long v = node.asLong();\nif (v < 0 || v > 4294967295L) {\n    throw new IllegalArgumentException(\"value out of uint32 range: \" + v);\n}","typeGuard":"node != null && (node.isInt() || node.isLong()) && node.asLong() >= 0 && node.asLong() <= 4294967295L","tryCatchPattern":"try { long u = MessageUtil.jsonNodeToUnsignedInt(node, about); }\ncatch (RuntimeException e) { /* log about + value, reject input */ }","preventionTips":["Keep uint32 fields within [0, 4294967295]; clamp or reject out-of-range values at your data boundary.","Validate ranges on the producer/ingest side, not just before serialization.","Treat unsigned-int fields as Java long in your own models to avoid silent sign truncation."],"tags":["kafka","protocol","json","serialization","uint32","range-error"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}