apache/kafka · error · IllegalArgumentException

Value %s must be one of %s

Error message

Value %s must be one of %s

What it means

Thrown by ElectionType.valueOf(byte) when deserializing an election type code from the wire (or any caller) that is neither 0 (PREFERRED) nor 1 (UNCLEAN). It is most often hit when the client receives an ElectLeaders response/request or admin invocation carrying an unexpected byte, or when application/protocol code passes an out-of-range election type. The message formats the offending value and the list of valid enum constants to aid diagnosis.

Source

Thrown at clients/src/main/java/org/apache/kafka/common/ElectionType.java:44

 * Options for {@link org.apache.kafka.clients.admin.Admin#electLeaders(ElectionType, Set, org.apache.kafka.clients.admin.ElectLeadersOptions)}.
 */
@InterfaceAudience.Public
public enum ElectionType {
    PREFERRED((byte) 0), UNCLEAN((byte) 1);

    public final byte value;

    ElectionType(byte value) {
        this.value = value;
    }

    public static ElectionType valueOf(byte value) {
        if (value == PREFERRED.value) {
            return PREFERRED;
        } else if (value == UNCLEAN.value) {
            return UNCLEAN;
        } else {
            throw new IllegalArgumentException(
                    String.format("Value %s must be one of %s", value, Arrays.asList(ElectionType.values())));
        }
    }
}

View on GitHub (pinned to c31c9215e1)

Solutions

1. Always use ElectionType.PREFERRED or ElectionType.UNCLEAN constants rather than raw bytes when calling Admin.electLeaders.
2. Upgrade the client jar to match (or exceed) the broker version so all wire-defined election types are recognized.
3. If deserializing from the wire, validate the byte against the known set before calling valueOf and surface a clearer protocol error.
4. For tests/mocks, use the enum constants or ElectionType.values() instead of hand-crafted integers.

Example fix

// before
ElectionType t = ElectionType.valueOf((byte) 2);  // throws 297
admin.electLeaders(t, partitions);

// after
ElectionType t = ElectionType.PREFERRED;  // 0
admin.electLeaders(t, partitions);

// Validate a byte against the known election types before calling ElectionType.valueOf:
byte candidate = value;
if (candidate != ElectionType.PREFERRED.value && candidate != ElectionType.UNCLEAN.value) {
    throw new IllegalArgumentException("Invalid election type byte: " + candidate
        + "; must be 0 (PREFERRED) or 1 (UNCLEAN)");
}
ElectionType type = ElectionType.valueOf(candidate);

import java.util.Arrays;
import java.util.Set;
import java.util.stream.Collectors;
import org.apache.kafka.common.ElectionType;

public static boolean isValidElectionType(byte id) {
    return id == ElectionType.PREFERRED.value || id == ElectionType.UNCLEAN.value;
}

public static Set<Byte> allowedElectionTypes() {
    return Arrays.stream(ElectionType.values())
        .map(t -> t.value).collect(Collectors.toSet());
}

try {
    ElectionType type = ElectionType.valueOf(id);
} catch (IllegalArgumentException e) {
    // Map to a user-facing 400 if it came from a request, or default to PREFERRED.
    throw new IllegalArgumentException("Unsupported election type " + id
        + "; supported values are 0 (PREFERRED), 1 (UNCLEAN)", e);
}

When it happens

Trigger: Admin.electLeaders being called with a manually-cast byte that is out of range; deserialization of a broker response that contains an election_type field with a value outside {0,1}; a broker-client version mismatch where a newer broker sends a value the older client enum does not know; reflection/manual byte construction passed into ElectionType.valueOf.

Common situations: Rolling upgrade where broker uses a new ElectionType value not yet present in the older client jar; tests/mocks that fabricate raw bytes; custom admin tooling that hardcodes an integer instead of using ElectionType.PREFERRED/UNCLEAN; cross-version cluster where a tool compiled against one Kafka version talks to another.

Related errors

• Unknown isolation level " + id
• Invalid leader epoch {leaderEpoch} (must be non-negative)
• Buffer underflow while parsing response for request with hea
• The response is unrelated to Sasl request since its correlat
• Unknown topology description status id: {id}

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