apache/flink · error · IllegalArgumentException

Configuration value %s overflows/underflows the integer type

Error message

Configuration value %s overflows/underflows the integer type.

What it means

Thrown by convertToInt when the raw value is a Long that falls outside the 32-bit signed integer range (less than Integer.MIN_VALUE or greater than Integer.MAX_VALUE). This happens when a YAML parser produces a Long for large numeric literals and the target ConfigOption is Integer-typed.

Source

Thrown at flink-core/src/main/java/org/apache/flink/configuration/ConfigurationUtils.java:531

    }

    static String convertToString(Object o) {
        if (o.getClass() == String.class) {
            return (String) o;
        } else {
            return YamlParserUtils.toYAMLString(o);
        }
    }

    static Integer convertToInt(Object o) {
        if (o.getClass() == Integer.class) {
            return (Integer) o;
        } else if (o.getClass() == Long.class) {
            long value = (Long) o;
            if (value <= Integer.MAX_VALUE && value >= Integer.MIN_VALUE) {
                return (int) value;
            } else {
                throw new IllegalArgumentException(
                        String.format(
                                "Configuration value %s overflows/underflows the integer type.",
                                value));
            }
        }

        return Integer.parseInt(o.toString());
    }

    static Long convertToLong(Object o) {
        if (o.getClass() == Long.class) {
            return (Long) o;
        } else if (o.getClass() == Integer.class) {
            return ((Integer) o).longValue();
        }

        return Long.parseLong(o.toString());
    }

View on GitHub (pinned to 2f3c205e92)

Solutions

Change the ConfigOption type to Long if the value legitimately exceeds int range.
Correct the value to fit within Integer range if an int is genuinely required.
Check for stray digits or incorrect units in the config value.

Example fix

// before
ConfigOption<Integer> opt = ConfigOptions.key("my.value").intType().defaultValue(0);
// value in yaml: my.value: 3000000000

// after
ConfigOption<Long> opt = ConfigOptions.key("my.value").longType().defaultValue(0L);

Defensive patterns

Strategy: validation

Validate before calling

long candidate = Long.parseLong(rawValue);
if (candidate < Integer.MIN_VALUE || candidate > Integer.MAX_VALUE) {
    throw new IllegalArgumentException("Value " + candidate + " exceeds int range");
}

Type guard

static boolean fitsInInt(long v) { return v >= Integer.MIN_VALUE && v <= Integer.MAX_VALUE; }

Try / catch

try {
    config.setInt(option, rawValue);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("overflows/underflows the integer")) { /* use long or fix */ }
}

Prevention

Use Long-typed ConfigOptions for values that may exceed int range.
Validate numeric ranges before setting config.
Double-check exponents and digit counts.

When it happens

Trigger: Declaring ConfigOption<Integer> and supplying a value that YAML parses as a Long because it exceeds Integer.MAX_VALUE (e.g., 3000000000). The guard at convertToInt checks bounds before the narrowing cast.

Common situations: Setting memory or port values that accidentally exceed int range. Typing an extra zero in a numeric config. Using a Long literal where an int was intended.

Related errors

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