apache/kafka · error · IllegalArgumentException

Invalid value `{}` for configuration {}. The value must eith

Error message

Invalid value `{}` for configuration {}. The value must either be 'batch_optimized' or 'record_limit'.

What it means

Thrown by ShareAcquireMode.of(String) when the supplied configuration value cannot be matched (case-insensitively) to either BATCH_OPTIMIZED or RECORD_LIMIT. The client validates the 'share.acquire.mode' config so that an unsupported mode cannot propagate into fetch/acquire requests. It surfaces as an IllegalArgumentException because the value is rejected before any enum constant exists.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareAcquireMode.java:49

    final byte id;

    ShareAcquireMode(final String name, final byte id) {
        this.name = name;
        this.id = id;
    }

    /**
     * Case-insensitive acquire mode lookup by string name.
     */
    public static ShareAcquireMode of(final String name) {
        if (name == null) {
            throw new IllegalArgumentException("ShareAcquireMode is null");
        }
        try {
            return ShareAcquireMode.valueOf(name.toUpperCase(Locale.ROOT));
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("Invalid value `" + name + "` for configuration " +
                name + ". The value must either be 'batch_optimized' or 'record_limit'.");
        }
    }

    public byte id() {
        return id;
    }

    public static ShareAcquireMode forId(byte id) {
        switch (id) {
            case 0:
                return BATCH_OPTIMIZED;
            case 1:
                return RECORD_LIMIT;
            default:
                throw new IllegalArgumentException("Unknown share acquire mode id: " + id);
        }
    }

View on GitHub (pinned to c31c9215e1)

Solutions

Set share.acquire.mode to exactly 'batch_optimized' or 'record_limit' (case-insensitive, no surrounding whitespace).
If constructing the enum programmatically, pass one of the documented string names instead of free text.
Validate the value at the config source (properties file / env var) before handing it to KafkaShareConsumer.

Example fix

// before
props.put("share.acquire.mode", "batch-optimized");

// after
props.put("share.acquire.mode", "batch_optimized");

Defensive patterns

Strategy: validation

Validate before calling

// Validate share acquire mode before building the consumer config.
import java.util.Locale;
import java.util.Set;
import java.util.Arrays;

Set<String> ALLOWED = Arrays.stream(ShareAcquireMode.values())
        .map(e -> e.name.toLowerCase(Locale.ROOT))
        .collect(java.util.stream.Collectors.toSet());

String acquireMode = props.getProperty("share.acquire.mode"); // or however you source it
if (acquireMode == null || !ALLOWED.contains(acquireMode.toLowerCase(Locale.ROOT))) {
    throw new IllegalArgumentException(
        "share.acquire.mode must be one of " + ALLOWED + " but was: " + acquireMode);
}

Type guard

// Narrow an arbitrary string to a known ShareAcquireMode before use.
public static Optional<ShareAcquireMode> asShareAcquireMode(String raw) {
    if (raw == null) return Optional.empty();
    try {
        return Optional.of(ShareAcquireMode.valueOf(raw.toUpperCase(Locale.ROOT)));
    } catch (IllegalArgumentException e) {
        return Optional.empty();
    }
}

Try / catch

// Only if you cannot pre-validate (e.g. user-supplied config map).
try {
    ShareAcquireMode.of(userValue);
} catch (IllegalArgumentException e) {
    // message tells the caller the two legal literals; surface to user/config UI.
    throw new ConfigException("share.acquire.mode", userValue, e.getMessage());
}

Prevention

Source share.acquire.mode from a typed enum in your own configuration object, never from a free-form String.
Centralize the set of allowed values by reflecting over ShareAcquireMode.values() so additions upstream do not silently break you.
Treat acquire-mode config as case-insensitive everywhere (the parser upper-cases), so do the same in your UI/docs.

When it happens

Trigger: Calling ShareAcquireMode.of(name) directly with a string other than 'batch_optimized' or 'record_limit' (e.g. 'none', 'earliest', 'batch'). Internally invoked when ConsumerConfig validates the share.acquire.mode property during KafkaShareConsumer construction or when the value is parsed from a properties map/JSON string.

Common situations: Typo in share.acquire.mode (e.g. 'batch-optimized' with a hyphen, 'BATCH' shorthand), copying a regular consumer's auto.offset.reset value into a share consumer config, or upgrading from a build that supported a now-removed mode name. Locale-specific uppercase folding also means trailing whitespace or BOM characters are not trimmed and will fail lookup.

Related errors

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