{"record":{"id":"f910adb28487dcf0","repo":"apache/flink","slug":"numeric-value-s-out-of-range-of-java-byte","errorCode":null,"errorMessage":"Numeric value (%s) out of range of Java byte.","messagePattern":"Numeric value \\((.+?)\\) out of range of Java byte\\.","errorType":"exception","errorClass":"org.apache.flink.formats.json.JsonParseException","httpStatus":null,"severity":"error","filePath":"flink-formats/flink-json/src/main/java/org/apache/flink/formats/json/JsonParserToRowDataConverters.java","lineNumber":212,"sourceCode":"    }\n\n    private boolean convertToBoolean(JsonParser jp) throws IOException {\n        if (jp.currentToken() == JsonToken.VALUE_TRUE) {\n            return true;\n        } else if (jp.currentToken() == JsonToken.VALUE_FALSE) {\n            return false;\n        } else {\n            return Boolean.parseBoolean(jp.getText().trim());\n        }\n    }\n\n    private byte convertToByte(JsonParser jp) throws IOException {\n        if (jp.currentToken() == JsonToken.VALUE_NUMBER_INT) {\n            // DON'T use jp.getByteValue() whose value is from -128 to 255 because of the unsigned\n            // value.\n            int value = jp.getIntValue();\n            if (value < Byte.MIN_VALUE || value > Byte.MAX_VALUE) {\n                throw new JsonParseException(\n                        String.format(\"Numeric value (%s) out of range of Java byte.\", value));\n            }\n            return (byte) value;\n        } else {\n            return Byte.parseByte(jp.getText().trim());\n        }\n    }\n\n    private short convertToShort(JsonParser jp) throws IOException {\n        if (jp.currentToken() == JsonToken.VALUE_NUMBER_INT) {\n            return jp.getShortValue();\n        } else {\n            return Short.parseShort(jp.getText().trim());\n        }\n    }\n\n    private int convertToInt(JsonParser jp) throws IOException {\n        if (jp.currentToken() == JsonToken.VALUE_NUMBER_INT","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-formats/flink-json/src/main/java/org/apache/flink/formats/json/JsonParserToRowDataConverters.java#L194-L230","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Widen the column: TINYINT -> INT or BIGINT in the DDL to match the data range","Fix the producer if values above 127/ below -128 are bugs","With ignore-parse-errors=true the row is skipped instead of failing the job (last-resort)"],"exampleFix":"-- before\nquantity TINYINT\n\n-- after\nquantity INT","handlingStrategy":"validation","validationCode":"// verify data range fits the column before/at ingest (e.g., in a UDF or upstream):\nif (value < Byte.MIN_VALUE || value > Byte.MAX_VALUE) { /* widen type or reject */ }","typeGuard":null,"tryCatchPattern":"catch (JsonParseException e) {\n    if (e.getMessage().contains(\"out of range of Java byte\")) {\n        // widen TINYINT -> INT in DDL and restart from checkpoint\n    }\n}","preventionTips":["Prefer INT over TINYINT for JSON sources unless the range is guaranteed","Check max(value) on real data before pinning narrow numeric types"],"tags":["flink","json","tinyint","overflow","schema"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}