apache/flink · error · IllegalArgumentException

Configuration value %s overflows/underflows the float type.

Error message

Configuration value %s overflows/underflows the float type.

What it means

Thrown by convertToFloat when the raw value is a Double whose magnitude exceeds Float.MAX_VALUE or underflows below Float.MIN_VALUE (excluding zero). This guard prevents silent precision/range loss when narrowing a Double to a Float.

Source

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

            default:
                throw new IllegalArgumentException(
                        String.format(
                                "Unrecognized option for boolean: %s. Expected either true or false(case insensitive)",
                                o));
        }
    }

    static Float convertToFloat(Object o) {
        if (o.getClass() == Float.class) {
            return (Float) o;
        } else if (o.getClass() == Double.class) {
            double value = ((Double) o);
            if (value == 0.0
                    || (value >= Float.MIN_VALUE && value <= Float.MAX_VALUE)
                    || (value >= -Float.MAX_VALUE && value <= -Float.MIN_VALUE)) {
                return (float) value;
            } else {
                throw new IllegalArgumentException(
                        String.format(
                                "Configuration value %s overflows/underflows the float type.",
                                value));
            }
        }

        return Float.parseFloat(o.toString());
    }

    static Double convertToDouble(Object o) {
        if (o.getClass() == Double.class) {
            return (Double) o;
        } else if (o.getClass() == Float.class) {
            return ((Float) o).doubleValue();
        }

        return Double.parseDouble(o.toString());
    }

View on GitHub (pinned to 2f3c205e92)

Solutions

Change the ConfigOption type to Double if the value legitimately exceeds float precision/range.
Adjust the value to stay within Float range.
Verify the exponent magnitude is what you intended.

Example fix

// before
ConfigOption<Float> opt = ConfigOptions.key("my.factor").floatType().defaultValue(1.0f);
// value: my.factor: 1e40

// after
ConfigOption<Double> opt = ConfigOptions.key("my.factor").doubleType().defaultValue(1.0);

Defensive patterns

Strategy: validation

Validate before calling

double candidate = Double.parseDouble(rawValue);
if (candidate != 0.0 && (Math.abs(candidate) > Float.MAX_VALUE || (Math.abs(candidate) < Float.MIN_VALUE))) {
    throw new IllegalArgumentException("Value exceeds float range");
}

Type guard

static boolean fitsInFloat(double v) {
    return v == 0.0 || (Math.abs(v) >= Float.MIN_VALUE && Math.abs(v) <= Float.MAX_VALUE);
}

Try / catch

try {
    config.set(floatOption, rawValue);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("overflows/underflows the float")) { /* use double */ }
}

Prevention

Use Double-typed ConfigOptions when precision/range may exceed float.
Validate exponent magnitude for float options.
Prefer double for scientific thresholds.

When it happens

Trigger: Declaring ConfigOption<Float> and supplying a value that YAML parses as a Double because it is outside the float range (e.g., 1e40 or 1e-50). The bound check in convertToFloat rejects out-of-range doubles.

Common situations: Setting thresholds or scaling factors with very large or very small exponents. Mixing double-literal syntax in configs targeting float options.

Related errors

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