apache/kafka · error · IllegalArgumentException

ShareAcquireMode is null

Error message

ShareAcquireMode is null

What it means

Thrown by ShareAcquireMode.of(String) when the supplied name is null. of() is the case-insensitive lookup that maps a config string to one of BATCH_OPTIMIZED or RECORD_LIMIT; a null input means the caller (usually the config layer) did not supply a value at all. This is a programmer/config error surfaced before any network activity.

Source

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

public enum ShareAcquireMode {
    BATCH_OPTIMIZED("batch_optimized", (byte) 0),
    RECORD_LIMIT("record_limit", (byte) 1);

    public final String name;

    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:

View on GitHub (pinned to c31c9215e1)

Solutions

1. Set share.acquire.mode to either "batch_optimized" or "record_limit" in consumer config.
2. Default the value programmatically: props.getOrDefault("share.acquire.mode", "batch_optimized").
3. Null-check the resolved config value at the boundary so the error message points at the missing property.

Example fix

// before
String mode = (String) props.get("share.acquire.mode");
ShareAcquireMode.of(mode); // throws if key absent

// after
String mode = (String) props.getOrDefault("share.acquire.mode", "batch_optimized");
ShareAcquireMode.of(mode);

// Validate the acquire-mode string before calling ShareAcquireMode.of().
String acquireMode = /* user/config supplied */ ;
if (acquireMode == null) {
    throw new IllegalArgumentException(
        "share acquire mode must not be null; expected 'batch_optimized' or 'record_limit'");
}
ShareAcquireMode.of(acquireMode);

java.util.function.Function<String, ShareAcquireMode> safeOf = s -> {
    if (s == null) {
        throw new IllegalArgumentException(
            "ShareAcquireMode is null; expected 'batch_optimized' or 'record_limit'");
    }
    return ShareAcquireMode.of(s);
};

try {
    ShareAcquireMode.of(acquireMode);
} catch (IllegalArgumentException ex) {
    // null or unknown acquire mode; default to a safe value or surface to the user
    ShareAcquireMode fallback = ShareAcquireMode.BATCH_OPTIMIZED;
}

When it happens

Trigger: Calling ShareAcquireMode.of(null) directly; the ShareAcquireMode.Validator running of() on a config property whose value resolved to null; passing a Map.get() result for share.acquire.mode without a default.

Common situations: Omitting share.acquire.mode while the share consumer requires it; using a placeholder (e.g. ${SHARE_ACQUIRE_MODE}) that resolved to null; building configs programmatically from a Map missing the key.

Related errors

• Acknowledgement mode is null
• Invalid acknowledgement mode: {}
• Invalid value `{}` for configuration {}. The value must eith
• Telemetry is not enabled. Set config `${ConsumerConfig.ENABL
• You must provide a valid ${ConsumerConfig.GROUP_ID_CONFIG} i

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