apache/kafka · error · IllegalStateException

Coordinator selected invalid assignment protocol: {}

Error message

Coordinator selected invalid assignment protocol: {}

What it means

IllegalStateException thrown from ConsumerCoordinator.onJoinComplete (ConsumerCoordinator.java:391) when the broker's SyncGroup response selects an assignment strategy whose name does not match any assignor configured on this client (lookupAssignor returns null). The client trusts the coordinator's choice, so an unknown name means this client and the rest of the group are out of sync. It typically signals a version skew or a missing custom assignor class rather than a broker bug.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/ConsumerCoordinator.java:391

        return null;
    }

    @SuppressWarnings("removal")
    @Override
    protected void onJoinComplete(int generation,
                                  String memberId,
                                  String assignmentStrategy,
                                  ByteBuffer assignmentBuffer) {
        log.debug("Executing onJoinComplete with generation {} and memberId {}", generation, memberId);

        // Only the leader is responsible for monitoring for metadata changes (i.e. partition changes)
        if (!isLeader)
            assignmentSnapshot = null;

        ConsumerPartitionAssignor assignor = lookupAssignor(assignmentStrategy);
        if (assignor == null)
            throw new IllegalStateException("Coordinator selected invalid assignment protocol: " + assignmentStrategy);

        // Give the assignor a chance to update internal state based on the received assignment
        groupMetadata = new ConsumerGroupMetadata(rebalanceConfig.groupId, generation, memberId, rebalanceConfig.groupInstanceId);

        SortedSet<TopicPartition> ownedPartitions = new TreeSet<>(COMPARATOR);
        ownedPartitions.addAll(subscriptions.assignedPartitions());

        // should at least encode the short version
        if (assignmentBuffer.remaining() < 2)
            throw new IllegalStateException("There are insufficient bytes available to read assignment from the sync-group response (" +
                "actual byte size " + assignmentBuffer.remaining() + ") , this is not expected; " +
                "it is possible that the leader's assign function is buggy and did not return any assignment for this member, " +
                "or because static member is configured and the protocol is buggy hence did not get the assignment for this member");

        Assignment assignment = ConsumerProtocol.deserializeAssignment(assignmentBuffer);

        SortedSet<TopicPartition> assignedPartitions = new TreeSet<>(COMPARATOR);
        assignedPartitions.addAll(assignment.partitions());

View on GitHub (pinned to c31c9215e1)

Solutions

Add the missing assignor class to this client's partition.assignment.strategy and ensure its JAR is on the classpath.
Roll all group members to the same Kafka client version so the assignor set is identical across the group.
For custom assignors, confirm the class's name() exactly matches what the leader advertised.
If the group is in a bad state, bounce the affected members or roll back to the previously working client version.

Defensive patterns

Strategy: try-catch

Try / catch

try {
    consumer.poll(Duration.ofSeconds(1));   // can surface during onJoinComplete
} catch (IllegalStateException e) {
    if (e.getMessage().contains("invalid assignment protocol")) {
        // broker returned a protocol this client doesn't know: rejoin with aligned config
        consumer.close();
        consumer = new KafkaConsumer<>(alignedProps);
        consumer.subscribe(topics);
    } else throw e;
}

Prevention

Keep the assignor class list identical across all members of the group.
Align client library versions in every member so the broker-selected protocol is always recognized.
Roll the whole consumer group together when deploying a new assignor — avoid mid-roll version skew.
Treat this as a deployment/compatibility fault, not transient: fix the config before retrying.

When it happens

Trigger: At the end of a successful rebalance, the coordinator returns assignmentStrategy='X'; ConsumerCoordinator.lookupAssignor('X') (ConsumerCoordinator.java:331) returns null because none of this client's assignors matches, so onJoinComplete throws.

Common situations: Broker-side group leader advertises an assignor this client does not ship (e.g. custom JAR missing from classpath); partial rollout of a new assignor across group members; client downgrade while the group still contains newer members; a custom assignor whose name() was changed between releases.

Related errors

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