apache/kafka · error · IllegalArgumentException

Illegal MetadataRecoveryStrategy: {name}

Error message

Illegal MetadataRecoveryStrategy: {name}

What it means

Thrown by MetadataRecoveryStrategy.forName(String) when the supplied strategy name is not null but does not match one of the enum constants (NONE, REBOOTSTRAP). The client uses this strategy to decide how to recover when every known broker node is unreachable. The IllegalArgumentException is raised by valueOf() after upper-casing the input, so it fires for any typo, unknown token, or unsupported value.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/MetadataRecoveryStrategy.java:41

 */
public enum MetadataRecoveryStrategy {
    NONE("none"),
    REBOOTSTRAP("rebootstrap");

    public final String name;

    MetadataRecoveryStrategy(String name) {
        this.name = name;
    }

    public static MetadataRecoveryStrategy forName(String name) {
        if (name == null) {
            throw new IllegalArgumentException("Illegal MetadataRecoveryStrategy: null");
        }
        try {
            return MetadataRecoveryStrategy.valueOf(name.toUpperCase(Locale.ROOT));
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("Illegal MetadataRecoveryStrategy: " + name);
        }
    }
}

View on GitHub (pinned to c31c9215e1)

Solutions

1. Set the property to a supported value: 'none' (default) or 'rebootstrap'.
2. Remove the property entirely to accept the default 'none'.
3. Trim/normalize whitespace and quotes in externalized config before passing to the client.
4. Upgrade the client to a version that supports the strategy name you intend to use.

Example fix

// before
props.put("client.rack.metadata.recovery.strategy", "re-bootstrap");
// after
props.put("client.rack.metadata.recovery.strategy", "rebootstrap");

// Validate the recovery-strategy name before calling MetadataRecoveryStrategy.forname(...)
String name = configValue; // user-supplied
if (name == null) {
    throw new IllegalArgumentException("MetadataRecoveryStrategy name must not be null");
}
java.util.Set<String> allowed = java.util.Arrays.stream(MetadataRecoveryStrategy.values())
        .map(s -> s.name.toLowerCase(java.util.Locale.ROOT))
        .collect(java.util.Collectors.toSet());
if (!allowed.contains(name.toLowerCase(java.util.Locale.ROOT))) {
    throw new IllegalArgumentException(
        "Invalid MetadataRecoveryStrategy '" + name + "'. Allowed: " + allowed);
}
MetadataRecoveryStrategy strategy = MetadataRecoveryStrategy.forname(name);

// Narrow an arbitrary string to a known strategy before use.
public static java.util.Optional<MetadataRecoveryStrategy> asStrategy(String name) {
    if (name == null) return java.util.Optional.empty();
    return java.util.Arrays.stream(MetadataRecoveryStrategy.values())
            .filter(s -> s.name.equalsIgnoreCase(name))
            .findFirst();
}
// Usage: asStrategy(raw).orElseThrow(() -> new IllegalArgumentException("bad strategy: " + raw));

try {
    MetadataRecoveryStrategy strategy = MetadataRecoveryStrategy.forname(userInput);
} catch (IllegalArgumentException e) {
    // surface a configuration error to the user, fall back to MetadataRecoveryStrategy.NONE,
    // or reject the config entirely. Do not silently ignore.
    throw new IllegalArgumentException("Bad client.metadata-recovery-strategy: " + userInput, e);
}

When it happens

Trigger: Client config property metadata recovery strategy is set to a string other than 'none' or 'rebootstrap' (case-insensitive). It is resolved via MetadataRecoveryStrategy.forName during NetworkClient construction / metadata updater setup. A null value is handled separately and produces a different message.

Common situations: Typo in client.rack.metadata.recovery.strategy or similar config key; passing a value valid in a newer broker version (e.g. a future strategy name) into an older client; externalized config file with stray whitespace or quotes around the value; default override left from experimentation.

Related errors

• No resolvable bootstrap urls given in bootstrap.servers
• Timeout needs to be greater than 0
• Invalid value `{}` for configuration {}. The value must eith
• JMX filter for configuration{metricsConfigPrefix}.(include/e
• Invalid url in bootstrap.servers: {url}

AI-assisted analysis of apache/kafka@c31c9215e1 (2026-08-03). Data as JSON: /data/errors/5fb3a154949aa449.json. Report an issue: GitHub.