apache/kafka · error · SchemaException

Malformed consumer protocol assignment

Error message

Malformed consumer protocol assignment

What it means

Thrown by ConsumerProtocol.deserializeAssignment(ByteBuffer, short) when reading the assignment payload fails. It wraps the underlying RuntimeException (most often BufferUnderflowException from a truncated payload) in a SchemaException, signalling that the bytes do not conform to the consumer-protocol assignment schema for the supplied version. The leader's assignment, produced by an assignor and forwarded by the broker, is what gets deserialized here.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/ConsumerProtocol.java:190

    public static Assignment deserializeAssignment(final ByteBuffer buffer, short version) {
        version = checkAssignmentVersion(version);

        try {
            ConsumerProtocolAssignment data =
                new ConsumerProtocolAssignment(new ByteBufferAccessor(buffer), version);

            List<TopicPartition> assignedPartitions = new ArrayList<>();
            for (ConsumerProtocolAssignment.TopicPartition tp : data.assignedPartitions()) {
                for (Integer partition : tp.partitions()) {
                    assignedPartitions.add(new TopicPartition(tp.topic(), partition));
                }
            }

            return new Assignment(
                assignedPartitions,
                data.userData() != null ? data.userData().duplicate() : null);
        } catch (RuntimeException e) {
            throw new SchemaException("Malformed consumer protocol assignment", e);
        }
    }

    public static Assignment deserializeAssignment(final ByteBuffer buffer) {
        return deserializeAssignment(buffer, deserializeVersion(buffer));
    }

    public static ConsumerProtocolAssignment deserializeConsumerProtocolAssignment(
        final ByteBuffer buffer,
        short version
    ) {
        version = checkAssignmentVersion(version);

        try {
            return new ConsumerProtocolAssignment(new ByteBufferAccessor(buffer), version);
        } catch (RuntimeException e) {
            throw new SchemaException("Malformed consumer protocol assignment", e);
        }

View on GitHub (pinned to c31c9215e1)

Solutions

1. Inspect the wrapped cause via e.getCause() to identify the failing field or the byte shortfall.
2. Confirm the assignor class is one Kafka ships (RangeAssignor, CooperativeStickyAssignor, etc.) or that the custom assignor delegates serialization to ConsumerProtocol.serializeAssignment.
3. Roll the consumer group members to the same client version so encoder and decoder agree on the schema.
4. Force a rejoin (consumer.enforceRebalance() / restart members) to discard any stale assignment payload.

// Pre-check buffer sanity before decoding the assignment body.
static void requireReadable(ByteBuffer buffer) {
    if (buffer == null) throw new IllegalArgumentException("buffer == null");
    if (buffer.remaining() < Short.BYTES)
        throw new IllegalArgumentException("assignment buffer too short to contain a version header");
}

try {
    Assignment assignment = ConsumerProtocol.deserializeAssignment(buffer, version);
} catch (org.apache.kafka.common.protocol.types.SchemaException e) {
    // Assignment payload (leader->member) is malformed — typically a corrupted/modified
    // ByteBuffer or a leader running an incompatible consumer protocol version.
    log.error("Malformed consumer protocol assignment", e);
    // Re-join the group so a new leader can recompute the assignment.
}

When it happens

Trigger: The consumer receives a SyncGroup response whose assignment ByteBuffer is shorter than expected or whose structure does not match ConsumerProtocolAssignment for the version indicated. Also triggered by custom assignors returning malformed assignment bytes.

Common situations: Client/broker version skew after a partial rolling upgrade; custom ConsumerPartitionAssignor that does not use ConsumerProtocol.serializeAssignment; network or compression layer truncating the assignment payload; corrupt group-state replay during coordinator failover.

Related errors

• Buffer underflow while parsing consumer protocol's header
• Malformed consumer protocol subscription
• Unsupported assignment version: {}
• Unsupported subscription version: {}
• Array size ${size} cannot be negative

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