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.

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)

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

• Invalid option %s. Must be a positive integer.
• A predicate on a BOOLEAN column requires a Boolean literal.
• Missing JobID. Specify a JobID to cancel a job.
• Failed to create enumerator for sourceIndex={currentSourceIn
• Invalid version %d

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