apache/kafka · error · RuntimeException

${about}: value ${value} does not fit in a 32-bit unsigned i

Error message

${about}: value ${value} does not fit in a 32-bit unsigned integer.

What it means

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.

Source

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

            throw new RuntimeException(about + ": value " + value +
                " does not fit in a 16-bit signed integer.");
        }
        return (short) value;
    }

    public static int jsonNodeToUnsignedShort(JsonNode node, String about) {
        int value = jsonNodeToInt(node, about);
        if (value < 0 || value > UNSIGNED_SHORT_MAX) {
            throw new RuntimeException(about + ": value " + value +
                " does not fit in a 16-bit unsigned integer.");
        }
        return value;
    }

    public static long jsonNodeToUnsignedInt(JsonNode node, String about) {
        long value = jsonNodeToLong(node, about);
        if (value < 0 || value > UNSIGNED_INT_MAX) {
            throw new RuntimeException(about + ": value " + value +
                    " does not fit in a 32-bit unsigned integer.");
        }
        return value;
    }

    public static int jsonNodeToInt(JsonNode node, String about) {
        if (node.isInt()) {
            return node.asInt();
        }
        if (node.isTextual()) {
            throw new NumberFormatException(about + ": expected an integer or " +
                "string type, but got " + node.getNodeType());
        }
        String text = node.asText();
        if (text.startsWith("0x")) {
            try {
                return Integer.parseInt(text.substring(2), 16);
            } catch (NumberFormatException e) {

View on GitHub (pinned to c31c9215e1)

Solutions

1. Inspect the 'about' prefix in the thrown message — it names the specific field that overflowed.
2. 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).
3. Regenerate/verify the JSON with a JSON validator and re-submit the request.
4. 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).

Example fix

// before
{"entity": {"client-id": 'app-1'}, "quotas": [{"key": "producer_byte_rate", "value": 6000000000}]}
// after  (cap under 2^32-1)
{"entity": {"client-id": 'app-1'}, "quotas": [{"key": "producer_byte_rate", "value": 1000000000}]}

long v = node.asLong();
if (v < 0 || v > 4294967295L) {
    throw new IllegalArgumentException("value out of uint32 range: " + v);
}

node != null && (node.isInt() || node.isLong()) && node.asLong() >= 0 && node.asLong() <= 4294967295L

try { long u = MessageUtil.jsonNodeToUnsignedInt(node, about); }
catch (RuntimeException e) { /* log about + value, reject input */ }

When it happens

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

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

Related errors

• ${about}: expected an integer or string type, but got ${node
• ${about}: failed to parse hexadecimal number: ${cause}
• ${about}: failed to parse number: ${cause}
• ${about}: expected Base64-encoded binary data.
• ${about}: unable to retrieve Base64-encoded binary data

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