apache/flink · error · org.apache.flink.formats.json.JsonParseException

Numeric value (%s) out of range of Java byte.

Error message

Numeric value (%s) out of range of Java byte.

What it means

JsonParseException from convertToByte when the parser sees a JSON integer token whose value is outside [-128, 127] for a TINYINT column. The code deliberately reads getIntValue() (because getByteValue() treats values as unsigned 0..255) and range-checks before narrowing, so this fires only for genuinely out-of-range integers, not for unsigned interpretation.

Source

Thrown at flink-formats/flink-json/src/main/java/org/apache/flink/formats/json/JsonParserToRowDataConverters.java:212

    }

    private boolean convertToBoolean(JsonParser jp) throws IOException {
        if (jp.currentToken() == JsonToken.VALUE_TRUE) {
            return true;
        } else if (jp.currentToken() == JsonToken.VALUE_FALSE) {
            return false;
        } else {
            return Boolean.parseBoolean(jp.getText().trim());
        }
    }

    private byte convertToByte(JsonParser jp) throws IOException {
        if (jp.currentToken() == JsonToken.VALUE_NUMBER_INT) {
            // DON'T use jp.getByteValue() whose value is from -128 to 255 because of the unsigned
            // value.
            int value = jp.getIntValue();
            if (value < Byte.MIN_VALUE || value > Byte.MAX_VALUE) {
                throw new JsonParseException(
                        String.format("Numeric value (%s) out of range of Java byte.", value));
            }
            return (byte) value;
        } else {
            return Byte.parseByte(jp.getText().trim());
        }
    }

    private short convertToShort(JsonParser jp) throws IOException {
        if (jp.currentToken() == JsonToken.VALUE_NUMBER_INT) {
            return jp.getShortValue();
        } else {
            return Short.parseShort(jp.getText().trim());
        }
    }

    private int convertToInt(JsonParser jp) throws IOException {
        if (jp.currentToken() == JsonToken.VALUE_NUMBER_INT

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Widen the column: TINYINT -> INT or BIGINT in the DDL to match the data range
2. Fix the producer if values above 127/ below -128 are bugs
3. With ignore-parse-errors=true the row is skipped instead of failing the job (last-resort)

Example fix

-- before
quantity TINYINT

-- after
quantity INT

// verify data range fits the column before/at ingest (e.g., in a UDF or upstream):
if (value < Byte.MIN_VALUE || value > Byte.MAX_VALUE) { /* widen type or reject */ }

catch (JsonParseException e) {
    if (e.getMessage().contains("out of range of Java byte")) {
        // widen TINYINT -> INT in DDL and restart from checkpoint
    }
}

When it happens

Trigger: JSON value like 200 or -300 landing in a TINYINT field (numeric token branch); note the string branch (Byte.parseByte) throws NumberFormatException instead, which surfaces as a field-level 'Fail to deserialize at field' error.

Common situations: Schema declared too narrow vs. real data (counts, ages, small codes overflowing 127); producer widening a field from tiny to int without updating the Flink DDL.

Related errors

• Unsupported type: {}
• JSON format doesn't support non-string as key type of map. T
• Some field is missing in the JSON data.
• Field types must not be null.
• Missing type for included field {}.

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/f910adb28487dcf0. Report an issue: GitHub.