apache/flink · error · IllegalArgumentException

Unrecognized option for boolean: %s. Expected either true or

Error message

Unrecognized option for boolean: %s. Expected either true or false(case insensitive)

What it means

Thrown by convertToBoolean when the raw value's string form (upper-cased) is neither TRUE nor FALSE. Boolean conversion only accepts the exact strings 'true' and 'false' in any case.

Source

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

        } else if (o.getClass() == Integer.class) {
            return ((Integer) o).longValue();
        }

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

    static Boolean convertToBoolean(Object o) {
        if (o.getClass() == Boolean.class) {
            return (Boolean) o;
        }

        switch (o.toString().toUpperCase()) {
            case "TRUE":
                return true;
            case "FALSE":
                return false;
            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(

View on GitHub (pinned to 2f3c205e92)

Solutions

Use exactly 'true' or 'false' (case-insensitive) as the config value.
If an empty string is the cause, ensure the env variable is actually set before it reaches Flink.
Convert yes/no or 1/0 style inputs to true/false upstream in your deployment scripts.

Example fix

# before
my.flag: yes

# after
my.flag: true

Defensive patterns

Strategy: validation

Validate before calling

String v = rawValue.trim();
if (!v.equalsIgnoreCase("true") && !v.equalsIgnoreCase("false")) {
    throw new IllegalArgumentException("Not a boolean: " + v);
}

Type guard

static boolean isFlinkBoolean(String s) {
    return s != null && (s.equalsIgnoreCase("true") || s.equalsIgnoreCase("false"));
}

Try / catch

try {
    config.set(boolOption, rawValue);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("Unrecognized option for boolean")) { /* normalize */ }
}

Prevention

Use only 'true'/'false' for boolean config values.
Normalize yes/no/on/off to true/false in deployment scripts.
Ensure env vars are set to avoid empty-string booleans.

When it happens

Trigger: Setting a Boolean ConfigOption to values like 'yes', 'no', '1', '0', 'on', 'off', or any non-'true'/'false' string. The conversion switch has no default numeric or alternative keyword handling.

Common situations: Coming from environments that accept yes/no or 1/0 for booleans. Shell variable expansion leaving an empty string. Copy-pasting config from other systems (e.g., systemd-style 'on').

Related errors

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