apache/flink · error · IllegalArgumentException

Value for config option %s must be one of %s (was %s)

Error message

Value for config option %s must be one of %s (was %s)

What it means

Configuration.getEnum(enumClass, configOption) converts the raw configured value into a constant of the given enum via ConfigurationUtils.convertToEnum. When the string does not equal (case-sensitively) any enum constant name, conversion throws and Flink rethrows IllegalArgumentException listing the option key, the allowed enum constants, and the offending value.

Source

Thrown at flink-core/src/main/java/org/apache/flink/configuration/Configuration.java:215

     *     be parsed as a value of the provided enum class.
     */
    @PublicEvolving
    public <T extends Enum<T>> T getEnum(
            final Class<T> enumClass, final ConfigOption<String> configOption) {
        checkNotNull(enumClass, "enumClass must not be null");
        checkNotNull(configOption, "configOption must not be null");

        Object rawValue = getRawValueFromOption(configOption).orElseGet(configOption::defaultValue);
        try {
            return ConfigurationUtils.convertToEnum(rawValue, enumClass);
        } catch (IllegalArgumentException ex) {
            final String errorMessage =
                    String.format(
                            "Value for config option %s must be one of %s (was %s)",
                            configOption.key(),
                            Arrays.toString(enumClass.getEnumConstants()),
                            rawValue);
            throw new IllegalArgumentException(errorMessage);
        }
    }

    // --------------------------------------------------------------------------------------------

    /**
     * Returns the keys of all key/value pairs stored inside this configuration object.
     *
     * @return the keys of all key/value pairs stored inside this configuration object
     */
    public Set<String> keySet() {
        synchronized (this.confData) {
            return new HashSet<>(this.confData.keySet());
        }
    }

    /** Adds all entries in this {@code Configuration} to the given {@link Properties}. */
    public void addAllToProperties(Properties props) {

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Correct the value to exactly one of the enum constants printed in the message (match spelling; note whether upper or lower case is required — convertToEnum is case-sensitive).
2. Check the option's documentation for its allowed values in your Flink version.
3. Remove the key to fall back to the option's default.
4. In YAML, quote the value if tooling mangles case.

Example fix

# before (flink-conf.yaml)
execution.checkpointing-consistency: exacly_once  # typo

# after
execution.checkpointing-consistency: EXACTLY_ONCE

static <E extends Enum<E>> boolean isValidEnumValue(Class<E> enumClass, String value) {
    for (E constant : enumClass.getEnumConstants()) {
        if (constant.name().equals(value)) return true;
    }
    return false;
}
// if (!isValidEnumValue(ConsistencyMode.class, conf.getString(key))) -> reject before getEnum

When it happens

Trigger: Setting e.g. 'execution.retry-policy: alwys' (typo), using wrong case ('EXACTLY_ONCE' vs expected spelling), providing an empty value, or a stale value after an enum constant was renamed between Flink versions.

Common situations: Hand-edited flink-conf.yaml / config map with a typo'd enum value; upgrading Flink where an option's allowed values changed; passing enum options via -Dkey=value on the CLI with a value that no longer exists.

Related errors

• Segment size must be a power of 2!
• {directory} is not a directory but a regular file
• Invalid port configuration. Port must be between 0and 65535,
• Invalid port configuration. Port must be between 0and 65535,
• Invalid port configuration. Port must be between 0and 65535,

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