apache/kafka · error · IllegalArgumentException

Illegal MetadataRecoveryStrategy: null

Error message

Illegal MetadataRecoveryStrategy: null

What it means

IllegalArgumentException from MetadataRecoveryStrategy.forName when the supplied name is null, or does not match one of the enum constants NONE/REBOOTSTRAP (compared case-insensitively via toUpperCase(ROOT)). Used by ClientUtils.createNetworkClient to convert the metadata.recovery.strategy config into the enum. The exception propagates wrapped in the NetworkClient KafkaException (error 17) if not handled earlier.

Solutions

1. Set metadata.recovery.strategy to either 'none' or 'rebootstrap' (case-insensitive).
2. If unset, rely on the documented default rather than passing a guessed value.
3. Validate before constructing the client: MetadataRecoveryStrategy.forName on a known-good literal.
4. On version upgrades, check the release notes for renamed/removed strategy values.

Example fix

# before
metadata.recovery.strategy=re-boot-strap
# after
metadata.recovery.strategy=rebootstrap

String name = config.getString(CommonClientConfigs.METADATA_RECOVERY_STRATEGY_CONFIG);
if (name == null || (!name.equalsIgnoreCase("none") && !name.equalsIgnoreCase("rebootstrap")))
  throw new ConfigException(CommonClientConfigs.METADATA_RECOVERY_STRATEGY_CONFIG, name, "must be 'none' or 'rebootstrap'");

// Narrow the string to the allowed set before calling forName
static final Set<String> ALLOWED = Set.of("none", "rebootstrap");
boolean isKnownStrategy(String s) { return s != null && ALLOWED.contains(s.toLowerCase(Locale.ROOT)); }

try { MetadataRecoveryStrategy.forName(name); } catch (IllegalArgumentException e) { /* set metadata.recovery.strategy to 'none' or 'rebootstrap' */ }

When it happens

Trigger: forName(null) throws immediately (line 39); forName("<unknown>") fails valueOf and is rethrown at line 44. Triggered when metadata.recovery.strategy is unset/empty or set to a value other than 'none'/'rebootstrap' (case-insensitive).

Common situations: Typo in metadata.recovery.strategy (e.g. 're-boot-strap'); value set to an old name removed in an upgrade; empty string from a templated config; passing a null from a defaulting bug.

Related errors

• Failed to create new NetworkClient
• Illegal MetadataRecoveryStrategy
• Invalid port in bootstrap.servers
• Invalid port in bootstrap.servers
• Invalid url in bootstrap.servers

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

Appendix: source

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

import java.util.Locale;

/**
 * Defines the strategies which clients can follow to deal with the situation when none of the known nodes is available.
 */
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)