{"id":"5a234cb096acd8a4","repo":"apache/kafka","slug":"about-value-value-does-not-fit-in-an-8-bit","errorCode":null,"errorMessage":"${about}: value ${value} does not fit in an 8-bit signed integer.","messagePattern":"(.+?): value (.+?) does not fit in an 8-bit signed integer\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/common/protocol/MessageUtil.java","lineNumber":75,"sourceCode":"        while (iter.hasNext()) {\n            Object object = iter.next();\n            bld.append(prefix);\n            bld.append(object.toString());\n            prefix = \", \";\n        }\n        bld.append(\"]\");\n        return bld.toString();\n    }\n\n    public static byte jsonNodeToByte(JsonNode node, String about) {\n        int value = jsonNodeToInt(node, about);\n        if (value > Byte.MAX_VALUE) {\n            if (value <= 256) {\n                // It's more traditional to refer to bytes as unsigned,\n                // so we support that here.\n                value -= 128;\n            } else {\n                throw new RuntimeException(about + \": value \" + value +\n                    \" does not fit in an 8-bit signed integer.\");\n            }\n        }\n        if (value < Byte.MIN_VALUE) {\n            throw new RuntimeException(about + \": value \" + value +\n                \" does not fit in an 8-bit signed integer.\");\n        }\n        return (byte) value;\n    }\n\n    public static short jsonNodeToShort(JsonNode node, String about) {\n        int value = jsonNodeToInt(node, about);\n        if ((value < Short.MIN_VALUE) || (value > Short.MAX_VALUE)) {\n            throw new RuntimeException(about + \": value \" + value +\n                \" does not fit in a 16-bit signed integer.\");\n        }\n        return (short) value;\n    }","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/common/protocol/MessageUtil.java#L57-L93","documentation":"Thrown by MessageUtil.jsonNodeToByte as a RuntimeException when the parsed integer value exceeds 256 (the upper tolerance band above Byte.MAX_VALUE used to support treating bytes as unsigned via the 0..255 remap). Any value above 256 cannot be losslessly stored in a Java signed byte, so the protocol/JSON deserializer refuses it. This guards JSON-driven message decoding paths (e.g. JSON-encoded requests/responses used by tooling and some serde paths) against out-of-range numeric fields.","triggerScenarios":"A JSON field that maps to a byte-typed protocol field is given an integer > 256 (or a '0x..' hex string decoding to > 256); jsonNodeToInt parses it, the 0..255 unsigned band is exceeded, and the error fires.","commonSituations":"Hand-editing a JSON request fixture or a connector config with a numeric value exceeding the field's 1-byte range; feeding a JSON record to a serde that packs a field into a byte; typo such as '2550' instead of '255'.","solutions":["Identify which field the 'about' string names and lower its value to <= 255 (or <= 127 if the field is genuinely signed).","If the value is hex ('0x...'), recompute it in decimal and confirm it is <= 0xFF (or <= 0x7F signed).","Switch the field's target type (e.g. to short) in your schema/message definition if the value legitimately exceeds one byte."],"exampleFix":"// before\n{ \"replicationFactor\": 2560 }\n\n// after\n{ \"replicationFactor\": 3 }","handlingStrategy":"validation","validationCode":"// MessageUtil.jsonNodeToByte accepts [-128, 256]; values in (127, 256] are remapped unsigned.\nint value = node.asInt();\nif (value < Byte.MIN_VALUE || value > 256) {\n    throw new IllegalArgumentException(about + \": value \" + value + \" outside byte range [-128,256]\");\n}\nbyte b = MessageUtil.jsonNodeToByte(node, about);","typeGuard":"// Narrow a JSON node to a validated byte before serialization.\nstatic Optional<Byte> asByte(com.fasterxml.jackson.databind.JsonNode n) {\n    if (n == null || !n.canConvertToInt()) return Optional.empty();\n    int v = n.asInt();\n    return (v >= Byte.MIN_VALUE && v <= 256) ? Optional.of((byte) v) : Optional.empty();\n}","tryCatchPattern":"try {\n    byte b = MessageUtil.jsonNodeToByte(node, about);\n} catch (RuntimeException e) {\n    // Unchecked: surfaced from JSON message serialization. Reject the input document.\n    log.error(\"{}: byte field out of range\", about, e);\n    rejectMessage(about, e);\n}","preventionTips":["Validate external JSON (config/spec files) against a schema with byte-range constraints before serialization.","Remember the asymmetric range: -128..127 signed, plus 128..256 tolerated as unsigned remap; above 256 always fails.","Prefer generating protocol JSON with code rather than hand-editing, so fields stay in range."],"tags":["protocol","json","serialization","out-of-range"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}