apache/kafka · error · IllegalArgumentException

Illegal MetadataRecoveryStrategy: {}

Error message

Illegal MetadataRecoveryStrategy: {}

What it means

Thrown by MetadataRecoveryStrategy.forName(String) when the supplied name is null or does not match any enum constant of MetadataRecoveryStrategy after uppercasing. The method resolves a recovery strategy by name (e.g. NONE, FETCH) and wraps the underlying Enum.valueOf failure in an IllegalArgumentException so callers get a single, consistent error type for both null input and bad names.

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 996fb4585a)

Solutions

1. Check the strategy name spelling against the MetadataRecoveryStrategy enum constants (NONE, FETCH, etc.) and correct the config value.
2. If the name comes from external input, validate it against MetadataRecoveryStrategy.values() before calling forName.
3. On Kafka version upgrades, verify the strategy name still exists in the target version's enum.

Example fix

// before
MetadataRecoveryStrategy.forName(userInput); // may throw

// after
if (userInput == null || Arrays.stream(MetadataRecoveryStrategy.values())
        .noneMatch(s -> s.name().equalsIgnoreCase(userInput))) {
    throw new IllegalArgumentException("Unknown strategy: " + userInput);
}
MetadataRecoveryStrategy.forName(userInput);

import java.util.Arrays;
boolean ok = name != null && Arrays.stream(MetadataRecoveryStrategy.values())
    .anyMatch(s -> s.name().equalsIgnoreCase(name));
if (!ok) throw new IllegalArgumentException("Invalid strategy: " + name);

static boolean isValidStrategyName(String name) {
    if (name == null) return false;
    return Arrays.stream(MetadataRecoveryStrategy.values())
        .anyMatch(s -> s.name().equalsIgnoreCase(name));
}

try {
    MetadataRecoveryStrategy.forName(name);
} catch (IllegalArgumentException e) {
    // log and fall back to default strategy or surface config error
}

When it happens

Trigger: Calling MetadataRecoveryStrategy.forName(name) with a null argument, or with a string that is not a valid enum constant name (e.g. "FOO", empty string, or a typo like "nones"). Also triggered by passing a config-derived string that has not been validated against the known strategy names.

Common situations: Misconfigured client property for metadata recovery strategy (typo in config key value), version mismatch where a strategy name was renamed or removed between Kafka versions, or programmatic construction where the name comes from an external/untrusted source without validation.

Related errors

• Illegal MetadataRecoveryStrategy: null
• There are no nodes in the Kafka cluster
• Timeout needs to be greater than 0
• must be non-null.
• enable.auto.commit cannot be set to true when default group

AI-assisted analysis of apache/kafka@996fb4585a (2026-08-11). Data as JSON: /api/errors/124f8aae9124ac6a. Report an issue: GitHub.