apache/flink · error · IllegalArgumentException

Could not parse value '%s' for key '%s'.

Error message

Could not parse value '%s' for key '%s'.

What it means

The non-sensitive variant of the getOptional parse failure: the raw value's string form is echoed ('Could not parse value '%s' for key '%s'') because the key did NOT match the sensitive-key patterns. It fires when ConfigurationUtils.convertValue/convertToList throws while turning the raw value into the ConfigOption's declared type — malformed duration/memory-size strings, non-numeric input for numeric options, or broken comma-separated list syntax.

Source

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

     */
    @PublicEvolving
    public <T> T get(ConfigOption<T> configOption, T overrideDefault) {
        return getOptional(configOption).orElse(overrideDefault);
    }

    @Override
    public <T> Optional<T> getOptional(ConfigOption<T> option) {
        Optional<Object> rawValue = getRawValueFromOption(option);
        Class<?> clazz = option.getClazz();

        try {
            if (option.isList()) {
                return rawValue.map(v -> ConfigurationUtils.convertToList(v, clazz));
            } else {
                return rawValue.map(v -> ConfigurationUtils.convertValue(v, clazz));
            }
        } catch (Exception e) {
            throw new IllegalArgumentException(
                    GlobalConfiguration.isSensitive(
                                    option.key(),
                                    this.get(SecurityOptions.ADDITIONAL_SENSITIVE_KEYS))
                            ? String.format("Could not parse value for key '%s'.", option.key())
                            : String.format(
                                    "Could not parse value '%s' for key '%s'.",
                                    rawValue.map(Object::toString).orElse(""), option.key()),
                    e);
        }
    }

    @Override
    public <T> Configuration set(ConfigOption<T> option, T value) {
        final boolean canBePrefixMap = canBePrefixMap(option);
        setValueInternal(option.key(), value, canBePrefixMap);
        return this;
    }

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Rewrite the value in the syntax the message's key expects — the echoed value shows exactly what failed; durations need a unit with a space ('30 s') or ISO-8601 ('PT30S'), memory sizes '256 mb', booleans 'true'/'false'.
2. Cross-check the option in the official config docs for its type in your Flink version.
3. Fix list options: comma-separated entries, each entry itself well-formed.
4. Remove the key to use the default while you verify the correct syntax.

Example fix

# before
state.backend.local-recovery: yes
heartbeat.interval: 10sec

# after
state.backend.local-recovery: true
heartbeat.interval: 10 s

static boolean parsesAs(Configuration conf, ConfigOption<Long> opt) {
    try {
        conf.getOptional(opt);
        return true;
    } catch (IllegalArgumentException e) {
        return false;
    }
}
// call all typed gets once at startup to surface bad values with full context

try {
    Duration d = conf.getOptional(MyOptions.TIMEOUT).orElse(Duration.ZERO);
} catch (IllegalArgumentException e) {
    // message contains the offending value and key; map to a config-validation report
    throw new ConfigValidationException(e.getMessage(), e);
}

When it happens

Trigger: Setting 'taskmanager.memory.network.size: 1gbx'; 'heartbeat.interval: 10sec' (missing space); a list option like 'parallelism.default' with junk; a boolean option given 'yes' instead of 'true'; empty value '' for a numeric option.

Common situations: Hand-edited flink-conf.yaml or Kubernetes config map typos; values copied from blog posts written for a different config syntax; upgrading Flink where an option changed from plain long to duration/memory type so old values no longer parse.

Related errors

• Could not parse value for key '%s'.
• Configuration cannot evaluate value %s as a byte[] value
• Value for config option %s must be one of %s (was %s)
• Unrecognized type: %s. This method is deprecated and might n
• Unrecognized type. This method is deprecated and might not w

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