apache/kafka · error · IllegalArgumentException

Unknown share acquire mode id: {}

Error message

Unknown share acquire mode id: {}

What it means

Thrown by ShareAcquireMode.forId(byte) when an internal wire/protocol byte identifier does not map to BATCH_OPTIMIZED (0) or RECORD_LIMIT (1). This is a defensive guard on the deserialization path: a byte id arrives from a fetch response, persisted state, or test fixture that is outside the known enum range. It indicates either a protocol mismatch or a forward-incompatible broker/client version pairing.

Source

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

            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);
        }
    }

    @Override
    public String toString() {
        return name;
    }

    public static class Validator implements ConfigDef.Validator {
        @Override
        public void ensureValid(String name, Object value) {
            String acquireMode = (String) value;
            try {
                of(acquireMode);
            } catch (Exception e) {
                throw new ConfigException(name, value, "Invalid value `" + acquireMode + "` for configuration " +
                    name + ". The value must either be 'batch_optimized' or 'record_limit'.");
            }

View on GitHub (pinned to c31c9215e1)

Solutions

1. Align client and broker to the same Kafka release line so the acquire-mode id vocabulary matches.
2. If hand-decoding protocol data, ensure the byte you pass is one returned by ShareAcquireMode.id() (currently 0 or 1).
3. Capture the exact byte id in logs and check the broker-side code that produced it for a version skew.

Example fix

// before
ShareAcquireMode mode = ShareAcquireMode.forId((byte) 5);

// after
ShareAcquireMode mode = ShareAcquireMode.forId(ShareAcquireMode.BATCH_OPTIMIZED.id());

// Validate a wire byte id before calling ShareAcquireMode.forId(byte).
public static boolean isLegalAcquireModeId(byte id) {
    return id == (byte) 0   // BATCH_OPTIMIZED
        || id == (byte) 1;  // RECORD_LIMIT
}

byte id = readFromWire();
if (!isLegalAcquireModeId(id)) {
    throw new IllegalArgumentException("Unsupported share acquire mode id: " + id);
}

// Narrow a byte to a known acquire mode without throwing.
public static Optional<ShareAcquireMode> acquireModeForId(byte id) {
    for (ShareAcquireMode m : ShareAcquireMode.values()) {
        if (m.id() == id) return Optional.of(m);
    }
    return Optional.empty();
}

// Only when you cannot inspect the byte first (e.g. third-party payload).
try {
    ShareAcquireMode.forId(id);
} catch (IllegalArgumentException e) {
    // Drop the record / close the connection: the producer used an unknown protocol value.
    log.warn("Ignoring record with unknown acquire mode id {}", id, e);
}

When it happens

Trigger: Calling ShareAcquireMode.forId(id) with a byte value other than 0 or 1. Reached when decoding a ShareFetchResponse or persisted acquire-mode state whose id field was written by a newer or non-conformant producer of the value, or in unit tests that hand-craft a byte id.

Common situations: Client and broker are on different Kafka versions where a new acquire-mode id was introduced on one side, a corrupted/transposed byte in a response buffer, or a test that passes an arbitrary constant. Because the value comes from the wire, end users almost never trigger it directly unless they downgrade a client against a newer broker.

Related errors

• Unexpected error code ${error.code()} while fetching from to
• Unexpected error code {} while fetching at offset {} from to
• Invalid value `{}` for configuration {}. The value must eith
• Record batch for partition {} at offset {} is invalid, cause
• Record for partition ${partition.topicPartition()} at offset

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