apache/kafka · error · KafkaException

List contains element of type {type}, expected String or Cla

Error message

List contains element of type {type}, expected String or Class

What it means

Thrown by ConsumerPartitionAssignor.getAssignorInstances when an element of the partition.assignment.strategy list is neither a String (class name) nor a Class object. The loader only knows how to handle those two forms, so any other Java type is rejected immediately rather than silently ignored. This is a programming/config-construction error, not a runtime data error.

Source

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

            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 996fb4585a)

Solutions

Ensure every element of partition.assignment.strategy is either a String FQN or a Class<?> reference, not a mix.
When loading config from JSON/YAML, coerce all strategy entries to String and let Kafka load the class.
Add a unit assertion that every list element is instanceof String || instanceof Class before constructing the consumer.

Example fix

// before
List<Object> strategies = new ArrayList<>();
strategies.add(CooperativeStickyAssignor.class);
strategies.add(someAssignorInstance); // wrong type
props.put(ConsumerConfig.PARTITION_ASSIGNMENT_STRATEGY_CONFIG, strategies);

// after
props.put(ConsumerConfig.PARTITION_ASSIGNMENT_STRATEGY_CONFIG,
    List.of(CooperativeStickyAssignor.class.getName()));

Defensive patterns

Strategy: validation

Validate before calling

List<String> safe = configuredStrategies.stream().map(o -> {
    if (o instanceof String) return (String) o;
    if (o instanceof Class<?>) return ((Class<?>) o).getName();
    throw new IllegalArgumentException("partition.assignment.strategy entry is neither String nor Class: " + o.getClass());
}).collect(Collectors.toList());
props.put(ConsumerConfig.PARTITION_ASSIGNMENT_STRATEGY_CONFIG, safe);

Type guard

static boolean isStrategyEntry(Object o) {
    return o instanceof String || o instanceof Class<?>;
}

Try / catch

try {
    consumer = new KafkaConsumer<>(props);
} catch (KafkaException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("List contains element of type ")) {
        // coerce the offending list to List<String> FQNs and rebuild props
    }
    throw e;
}

Prevention

Always build partition.assignment.strategy as List<String> of FQNs; never mix types.
When loading config from JSON/YAML, force every strategy entry to String.
Unit-test the config builder to assert homogeneous list element types.

When it happens

Trigger: Passing a List containing a Class instance plus a non-class object (e.g. a Map, an assignor instance, or a Path); constructing the config programmatically with mixed element types; serializing/deserializing config in a way that turns class names into typed objects.

Common situations: Building ConsumerConfig from a JSON/Properties source that interpreted one entry as an object; tests that hand-construct the assignor list with helper methods returning heterogeneous types; framework glue that injects pre-instantiated objects into the strategy list.

Related errors

AI-assisted analysis of apache/kafka@996fb4585a (2026-08-11). Data as JSON: /api/errors/1c54ebd557f3c8fa. Report an issue: GitHub.