{"record":{"id":"fb3d9de66cb802ff","repo":"apache/flink","slug":"cannot-downcast-long-value-to-integer","errorCode":null,"errorMessage":"Cannot downcast long value {} to integer.","messagePattern":"Cannot downcast long value (.+?) to integer\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/util/MathUtils.java","lineNumber":88,"sourceCode":"        return Integer.highestOneBit(value);\n    }\n\n    /**\n     * Casts the given value to a 32 bit integer, if it can be safely done. If the cast would change\n     * the numeric value, this method raises an exception.\n     *\n     * <p>This method is a protection in places where one expects to be able to safely case, but\n     * where unexpected situations could make the cast unsafe and would cause hidden problems that\n     * are hard to track down.\n     *\n     * @param value The value to be cast to an integer.\n     * @return The given value as an integer.\n     * @see Math#toIntExact(long)\n     */\n    public static int checkedDownCast(long value) {\n        int downCast = (int) value;\n        if (downCast != value) {\n            throw new IllegalArgumentException(\n                    \"Cannot downcast long value \" + value + \" to integer.\");\n        }\n        return downCast;\n    }\n\n    /**\n     * Checks whether the given value is a power of two.\n     *\n     * @param value The value to check.\n     * @return True, if the value is a power of two, false otherwise.\n     */\n    public static boolean isPowerOf2(long value) {\n        return (value & (value - 1)) == 0;\n    }\n\n    /**\n     * This function hashes an integer value. It is adapted from Bob Jenkins' website <a\n     * href=\"http://www.burtleburtle.net/bob/hash/integer.html\">http://www.burtleburtle.net/bob/hash/integer.html</a>.","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/util/MathUtils.java#L70-L106","documentation":"MathUtils.checkedDownCast safely narrows a long to int: it performs the cast, then verifies the int round-trips back to the original long; if information was lost (value outside [-2^31, 2^31-1]) it throws IllegalArgumentException. It exists to turn silent truncation in size/length math into a loud failure (mirroring JDK Math.toIntExact but throwing IAE).","triggerScenarios":"Calling checkedDownCast(v) with v > Integer.MAX_VALUE or v < Integer.MIN_VALUE — commonly byte sizes, counts, or offsets computed in long that exceed 2^31-1 (over 2 GiB / ~2.1 billion elements).","commonSituations":"File or memory sizes above 2 GiB passed through int-typed APIs; large state sizes or network buffer byte counts from configuration parsing (MemorySize in bytes); result-set row counts or offsets exceeding int range in oversized test data generation.","solutions":["Check the value printed in the message: if > 2147483647, the quantity genuinely exceeds int range — restructure the API to carry long end-to-end instead of casting.","If the value is absurdly large, fix the upstream computation (e.g. a unit mismatch passing bytes where elements were expected, or a multiplied size).","Split large work into chunks under 2^31 units and cast per chunk.","Widen the consuming field/parameter from int to long so no downcast is needed."],"exampleFix":"// before\nint sizeInBytes = MathUtils.checkedDownCast(fileSizeInBytes); // >2GiB -> IAE\n\n// after\nlong sizeInBytes = fileSizeInBytes;\n// or chunk:\nwhile (remaining > 0) {\n    int chunk = MathUtils.checkedDownCast(Math.min(remaining, Integer.MAX_VALUE));\n    process(chunk);\n    remaining -= chunk;\n}","handlingStrategy":"validation","validationCode":"if (value > Integer.MAX_VALUE || value < Integer.MIN_VALUE) {\n    throw new IllegalArgumentException(\"value \" + value + \" exceeds int range; use long or chunk the work\");\n}\nint i = MathUtils.checkedDownCast(value);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep byte sizes and counts as long until the final consumer","Chunk transfers larger than 2^31 units","Watch unit mismatches (bytes vs elements) that inflate longs"],"tags":["math","overflow","casting","sizing","validation"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}