apache/kafka · error · InvalidGroupIdException

You must provide a valid ${ConsumerConfig.GROUP_ID_CONFIG} i

Error message

You must provide a valid ${ConsumerConfig.GROUP_ID_CONFIG} in the consumer configuration.

What it means

Thrown by maybeThrowInvalidGroupIdException() (line 1173) as InvalidGroupIdException when groupId is null or empty. The share consumer mandates a group.id because share-group membership is what the broker uses to assign and track delivery of records to this consumer. It is checked in the constructor (line 251) and again in subscribe() (line 550), so both eager and lazy usage fail fast.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/ShareConsumerImpl.java:1173

        }
        refCount.incrementAndGet();
    }

    /**
     * Release the light lock protecting the consumer from multithreaded access.
     */
    private void release() {
        if (refCount.decrementAndGet() == 0)
            currentThread.set(NO_CURRENT_THREAD);
    }

    public static LogContext createLogContext(final String clientId, final String groupId) {
        return new LogContext("[ShareConsumer clientId=" + clientId + ", groupId=" + groupId + "] ");
    }

    private void maybeThrowInvalidGroupIdException() {
        if (groupId == null || groupId.isEmpty()) {
            throw new InvalidGroupIdException(
                    "You must provide a valid " + ConsumerConfig.GROUP_ID_CONFIG + " in the consumer configuration.");
        }
    }

    /**
     * Handles any completed acknowledgements. If there is an acknowledgement commit callback registered,
     * call it. Otherwise, discard the information about completed acknowledgements because the application
     * is not interested.
     */
    private void handleCompletedAcknowledgements() {
        if (acknowledgementEventQueue == null || acknowledgementEventHandler == null) {
            return;
        }

        processAcknowledgementEvents();

        if (!completedAcknowledgements.isEmpty()) {
            try {

View on GitHub (pinned to c31c9215e1)

Solutions

Set group.id to a non-empty string in the consumer properties: props.put(ConsumerConfig.GROUP_ID_CONFIG, "order-share-group").
If using Spring/Quarkus, ensure @Value or @ConfigurationProperties actually resolves the property and is not blank.
Validate required config at startup — fail the application context if group.id is missing rather than letting the consumer throw later.
For multiple share groups, instantiate one consumer per group, each with its own distinct group.id.

Example fix

// before
props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, brokers);
new KafkaShareConsumer<String,String>(props);

// after
props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, brokers);
props.put(ConsumerConfig.GROUP_ID_CONFIG, "order-share-group");
new KafkaShareConsumer<String,String>(props);

Defensive patterns

Strategy: validation

Validate before calling

// Validate group.id before constructing the ShareConsumer.
String groupId = (String) props.get(org.apache.kafka.clients.consumer.ConsumerConfig.GROUP_ID_CONFIG);
if (groupId == null || groupId.trim().isEmpty()) {
    throw new IllegalArgumentException(
        "ShareConsumer requires a non-empty " + org.apache.kafka.clients.consumer.ConsumerConfig.GROUP_ID_CONFIG);
}
new org.apache.kafka.clients.consumer.KafkaShareConsumer<>(props, keyDeser, valueDeser);

Type guard

null

Try / catch

try {
    consumer = new org.apache.kafka.clients.consumer.KafkaShareConsumer<>(props, keyDeser, valueDeser);
} catch (org.apache.kafka.common.errors.InvalidGroupIdException e) {
    // configuration error: fix group.id and rebuild props before retrying
    props.put(org.apache.kafka.clients.consumer.ConsumerConfig.GROUP_ID_CONFIG, requiredGroupId);
    throw e;
}

Prevention

Share consumption always requires a group.id; set it once in a central config builder.
Fail fast at startup by asserting group.id is present rather than discovering it on first poll.
Do not reuse a properties object that previously had group.id removed for another use case.

When it happens

Trigger: Constructing KafkaShareConsumer with a properties map missing group.id, or with group.id set to an empty string. Also reached when subscribe(...) is called on a consumer whose group.id resolved to null via a ConfigProvider that returned no value.

Common situations: Share-consumer quickstart that copies a regular consumer example but omits group.id; Spring Boot @ConfigurationProperties binding that did not map the group.id property; templated config where ${KAFKA_GROUP} was unset and expanded to empty; multiple consumer beans sharing a base config where the group.id override was forgotten on one.

Related errors

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