apache/flink · error · IllegalArgumentException

Cannot downcast long value {} to integer.

Error message

Cannot downcast long value {} to integer.

What it means

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).

Source

Thrown at flink-core/src/main/java/org/apache/flink/util/MathUtils.java:88

        return Integer.highestOneBit(value);
    }

    /**
     * Casts the given value to a 32 bit integer, if it can be safely done. If the cast would change
     * the numeric value, this method raises an exception.
     *
     * <p>This method is a protection in places where one expects to be able to safely case, but
     * where unexpected situations could make the cast unsafe and would cause hidden problems that
     * are hard to track down.
     *
     * @param value The value to be cast to an integer.
     * @return The given value as an integer.
     * @see Math#toIntExact(long)
     */
    public static int checkedDownCast(long value) {
        int downCast = (int) value;
        if (downCast != value) {
            throw new IllegalArgumentException(
                    "Cannot downcast long value " + value + " to integer.");
        }
        return downCast;
    }

    /**
     * Checks whether the given value is a power of two.
     *
     * @param value The value to check.
     * @return True, if the value is a power of two, false otherwise.
     */
    public static boolean isPowerOf2(long value) {
        return (value & (value - 1)) == 0;
    }

    /**
     * This function hashes an integer value. It is adapted from Bob Jenkins' website <a
     * href="http://www.burtleburtle.net/bob/hash/integer.html">http://www.burtleburtle.net/bob/hash/integer.html</a>.

View on GitHub (pinned to 2f3c205e92)

Solutions

1. 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.
2. 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).
3. Split large work into chunks under 2^31 units and cast per chunk.
4. Widen the consuming field/parameter from int to long so no downcast is needed.

Example fix

// before
int sizeInBytes = MathUtils.checkedDownCast(fileSizeInBytes); // >2GiB -> IAE

// after
long sizeInBytes = fileSizeInBytes;
// or chunk:
while (remaining > 0) {
    int chunk = MathUtils.checkedDownCast(Math.min(remaining, Integer.MAX_VALUE));
    process(chunk);
    remaining -= chunk;
}

if (value > Integer.MAX_VALUE || value < Integer.MIN_VALUE) {
    throw new IllegalArgumentException("value " + value + " exceeds int range; use long or chunk the work");
}
int i = MathUtils.checkedDownCast(value);

When it happens

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

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

Related errors

• Logarithm of zero is undefined.
• The given value {} is not a power of two.
• {e.getMessage()}
• Cannot access jar file{t.getMessage() == null ? "." : ": " +
• The jarFile and entryPointClassName can not be null at the s

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