apache/kafka · error · KafkaException

{klass} is not an instance of org.apache.kafka.clients.consu

Error message

{klass} is not an instance of org.apache.kafka.clients.consumer.ConsumerPartitionAssignor

What it means

Thrown when an entry of partition.assignment.strategy loads successfully (as a String class name or a Class) but the instantiated object does not implement ConsumerPartitionAssignor. The assignor list only accepts objects the consumer can drive through the partition assignment contract.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerPartitionAssignor.java:447

                    throw new KafkaException(klass + " ClassNotFoundException exception occurred", classNotFound);
                }
            }

            if (klass instanceof Class<?>) {
                Object assignor = Utils.newInstance((Class<?>) klass);
                if (assignor instanceof Configurable)
                    ((Configurable) assignor).configure(configs);

                if (assignor instanceof ConsumerPartitionAssignor) {
                    String assignorName = ((ConsumerPartitionAssignor) assignor).name();
                    if (assignorNameMap.containsKey(assignorName)) {
                        throw new KafkaException("The assignor name: '" + assignorName + "' is used in more than one assignor: " +
                            assignorNameMap.get(assignorName) + ", " + assignor.getClass().getName());
                    }
                    assignorNameMap.put(assignorName, assignor.getClass().getName());
                    assignors.add((ConsumerPartitionAssignor) assignor);
                } else {
                    throw new KafkaException(klass + " is not an instance of " + ConsumerPartitionAssignor.class.getName());
                }
            } else {
                throw new KafkaException("List contains element of type " + klass.getClass().getName() + ", expected String or Class");
            }
        }
        return assignors;
    }

}

View on GitHub (pinned to c31c9215e1)

Solutions

Verify every entry in partition.assignment.strategy is a class implementing org.apache.kafka.clients.consumer.ConsumerPartitionAssignor (e.g. RangeAssignor, CooperativeStickyAssignor).
Correct the typo'd class name or replace it with a built-in assignor class name.
If using a custom assignor, confirm it declares `implements ConsumerPartitionAssignor` and the fully-qualified name in config matches the compiled class.

Example fix

// before
props.put(ConsumerConfig.PARTITION_ASSIGNMENT_STRATEGY_CONFIG,
    "org.apache.kafka.clients.producer.RoundRobinPartitioner");

// after
props.put(ConsumerConfig.PARTITION_ASSIGNMENT_STRATEGY_CONFIG,
    "org.apache.kafka.clients.consumer.RoundRobinAssignor");

Defensive patterns

Strategy: type-guard

Validate before calling

// Verify each entry actually implements ConsumerPartitionAssignor before it reaches the consumer
List<Class<?>> safe = new ArrayList<>();
for (Object entry : assignorList) {
    Class<?> c = (entry instanceof String) ? Class.forName((String) entry) : (Class<?>) entry;
    if (!ConsumerPartitionAssignor.class.isAssignableFrom(c)) {
        throw new IllegalArgumentException(c.getName() + " is not a ConsumerPartitionAssignor; check partition.assignment.strategy");
    }
    safe.add(c);
}

Type guard

static boolean isAssignor(Object entry) throws ClassNotFoundException {
    Class<?> c = (entry instanceof String) ? Class.forName((String) entry) : (Class<?>) entry;
    return ConsumerPartitionAssignor.class.isAssignableFrom(c);
}

Try / catch

try {
    new KafkaConsumer<>(props);
} catch (KafkaException e) {
    if (e.getMessage() != null && e.getMessage().contains("is not an instance of")) {
        // strip the offending class from partition.assignment.strategy and rebuild props
    }
    throw e;
}

Prevention

partition.assignment.strategy only accepts fully-qualified class names (Strings) or Class objects that implement ConsumerPartitionAssignor.
For custom assignors, declare `implements ConsumerPartitionAssignor` explicitly rather than a sibling interface.
Treat a typo in the class name as a likely cause: it loads a class that exists but is not an assignor.

When it happens

Trigger: Passing a fully-qualified class name in partition.assignment.strategy that resolves to a producer interceptor, serializer, or any class that is not a ConsumerPartitionAssignor; passing a Class<?> literal of the wrong type.

Common situations: Copy-paste errors putting ConsumerInterceptor or ProducerPartitionAssignor-like class names into the strategy list; misreading docs and supplying a class name from another framework (e.g. a Connect connector class); shaded class relocation pointing at the wrong class.

Related errors

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