apache/kafka · error · RuntimeException

${about}: value ${value} does not fit in an 8-bit signed int

Error message

${about}: value ${value} does not fit in an 8-bit signed integer.

What it means

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.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/protocol/MessageUtil.java:75

        while (iter.hasNext()) {
            Object object = iter.next();
            bld.append(prefix);
            bld.append(object.toString());
            prefix = ", ";
        }
        bld.append("]");
        return bld.toString();
    }

    public static byte jsonNodeToByte(JsonNode node, String about) {
        int value = jsonNodeToInt(node, about);
        if (value > Byte.MAX_VALUE) {
            if (value <= 256) {
                // It's more traditional to refer to bytes as unsigned,
                // so we support that here.
                value -= 128;
            } else {
                throw new RuntimeException(about + ": value " + value +
                    " does not fit in an 8-bit signed integer.");
            }
        }
        if (value < Byte.MIN_VALUE) {
            throw new RuntimeException(about + ": value " + value +
                " does not fit in an 8-bit signed integer.");
        }
        return (byte) value;
    }

    public static short jsonNodeToShort(JsonNode node, String about) {
        int value = jsonNodeToInt(node, about);
        if ((value < Short.MIN_VALUE) || (value > Short.MAX_VALUE)) {
            throw new RuntimeException(about + ": value " + value +
                " does not fit in a 16-bit signed integer.");
        }
        return (short) value;
    }

View on GitHub (pinned to c31c9215e1)

Solutions

1. Identify which field the 'about' string names and lower its value to <= 255 (or <= 127 if the field is genuinely signed).
2. If the value is hex ('0x...'), recompute it in decimal and confirm it is <= 0xFF (or <= 0x7F signed).
3. Switch the field's target type (e.g. to short) in your schema/message definition if the value legitimately exceeds one byte.

Example fix

// before
{ "replicationFactor": 2560 }

// after
{ "replicationFactor": 3 }

// MessageUtil.jsonNodeToByte accepts [-128, 256]; values in (127, 256] are remapped unsigned.
int value = node.asInt();
if (value < Byte.MIN_VALUE || value > 256) {
    throw new IllegalArgumentException(about + ": value " + value + " outside byte range [-128,256]");
}
byte b = MessageUtil.jsonNodeToByte(node, about);

// Narrow a JSON node to a validated byte before serialization.
static Optional<Byte> asByte(com.fasterxml.jackson.databind.JsonNode n) {
    if (n == null || !n.canConvertToInt()) return Optional.empty();
    int v = n.asInt();
    return (v >= Byte.MIN_VALUE && v <= 256) ? Optional.of((byte) v) : Optional.empty();
}

try {
    byte b = MessageUtil.jsonNodeToByte(node, about);
} catch (RuntimeException e) {
    // Unchecked: surfaced from JSON message serialization. Reject the input document.
    log.error("{}: byte field out of range", about, e);
    rejectMessage(about, e);
}

When it happens

Trigger: 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.

Common situations: 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'.

Related errors

• ${about}: value ${value} does not fit in a 16-bit signed int
• ${about}: value ${value} does not fit in a 16-bit unsigned i
• ${about}: value ${value} does not fit in a 32-bit unsigned i
• ${about}: expected an integer or string type, but got ${node
• ${about}: failed to parse hexadecimal number: ${cause}

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/5a234cb096acd8a4.json. Report an issue: GitHub.