apache/flink · error · IllegalArgumentException

${message}

Error message

${message}

What it means

ConfigurationValidatorUtil#validateOptionalBooleanProperty throws IllegalArgumentException (with the caller-supplied message) when a config property that is present is neither 'true' nor 'false'. Only string values exactly equal to those literals are accepted.

Solutions

1. Set the property value to exactly 'true' or 'false' (lowercase, no whitespace).
2. If loading from a file, trim whitespace before validation.
3. Pre-validate the property and normalize it (e.g. parse Boolean.parseString then write back the canonical form).

Example fix

// before
props.setProperty("enable-feature", "1");
ConfigurationValidatorUtil.validateOptionalBooleanProperty(props, "enable-feature", msg);
// after
props.setProperty("enable-feature", "true");

static void ensureBoolean(Properties p, String k) {
    if (p.containsKey(k)) {
        String v = p.getProperty(k).trim();
        if (!v.equals("true") && !v.equals("false")) {
            throw new IllegalArgumentException(k + " must be 'true' or 'false' but was: " + v);
        }
        p.setProperty(k, v);
    }
}

static boolean isCanonicalBoolean(Properties p, String k) {
    return !p.containsKey(k)
        || p.getProperty(k).equals("true")
        || p.getProperty(k).equals("false");
}

When it happens

Trigger: A Properties config contains a key expected to be boolean but with a value like '1', 'yes', 'TRUE ' (with trailing space), or any non-literal.

Common situations: Properties file with non-canonical boolean strings; migration from a system that used 0/1; trailing whitespace in config values.

Related errors

• A predicate on a BOOLEAN column requires a Boolean literal.
• Invalid option . Must be a positive integer.
• A predicate on a FLOAT column requires a floating literal…
• A predicate on a LONG column requires an integer literal…
• A predicate on a STRING column requires a floating literal…

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

Appendix: source

Thrown at flink-connectors/flink-connector-base/src/main/java/org/apache/flink/connector/base/table/util/ConfigurationValidatorUtil.java:36

package org.apache.flink.connector.base.table.util;

import org.apache.flink.annotation.PublicEvolving;
import org.apache.flink.connector.base.table.options.ConfigurationValidator;

import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Properties;

/** Class containing validation utils needed by {@link ConfigurationValidator}. */
@PublicEvolving
public class ConfigurationValidatorUtil {
    public static void validateOptionalBooleanProperty(
            Properties config, String key, String message) {
        if (config.containsKey(key)) {
            if (!config.getProperty(key).equals("true")
                    && !config.getProperty(key).equals("false")) {
                throw new IllegalArgumentException(message);
            }
        }
    }

    public static void validateOptionalPositiveIntProperty(
            Properties config, String key, String message) {
        if (config.containsKey(key)) {
            try {
                int value = Integer.parseInt(config.getProperty(key));
                if (value < 0) {
                    throw new NumberFormatException();
                }
            } catch (NumberFormatException e) {
                throw new IllegalArgumentException(message);
            }
        }
    }

View on GitHub (pinned to 2f3c205e92)