apache/kafka · error · org.apache.kafka.common.errors.InvalidGroupIdException

To use the group management or offset commit APIs, you must

Error message

To use the group management or offset commit APIs, you must provide a valid group.id in the consumer configuration.

What it means

Thrown by throwIfGroupIdNotDefined() when a consumer operation that requires group membership is invoked but the consumer has no group.id configured. The new async consumer guards group-management and offset-commit APIs (commitSync/commitAsync, committed, groupMetadata, etc.) because without a group there is no coordinator to track membership or store committed offsets. It is an InvalidGroupIdException, a subclass of ApiException, signalling a configuration error rather than a transient failure.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/AsyncKafkaConsumer.java:1293

            wakeupTrigger.setActiveTask(event.future());
            try {
                return applicationEventHandler.addAndGet(event);
            } catch (TimeoutException e) {
                throw new TimeoutException("Timeout of " + timeout.toMillis() + "ms expired before the last " +
                    "committed offset for partitions " + partitions + " could be determined. Try tuning " +
                    ConsumerConfig.DEFAULT_API_TIMEOUT_MS_CONFIG + " larger to relax the threshold.");
            } finally {
                wakeupTrigger.clearTask();
            }
        } finally {
            kafkaConsumerMetrics.recordCommitted(time.nanoseconds() - start);
            release();
        }
    }

    private void throwIfGroupIdNotDefined() {
        if (groupMetadata.get().isEmpty()) {
            throw new InvalidGroupIdException("To use the group management or offset commit APIs, you must " +
                "provide a valid " + ConsumerConfig.GROUP_ID_CONFIG + " in the consumer configuration.");
        }
    }

    @Override
    public Map<MetricName, ? extends Metric> metrics() {
        return Collections.unmodifiableMap(metrics.metrics());
    }

    @Override
    public List<PartitionInfo> partitionsFor(String topic) {
        return partitionsFor(topic, defaultApiTimeoutMs);
    }

    @Override
    public List<PartitionInfo> partitionsFor(String topic, Duration timeout) {
        acquireAndEnsureOpen();
        try {

View on GitHub (pinned to c31c9215e1)

Solutions

Set ConsumerConfig.GROUP_ID_CONFIG to a non-empty string in the consumer properties before constructing the consumer.
If you intend manual partition assignment with no group, remove the offending commit/group calls; manual assign() does not require group.id but commit*() still does.
Verify no wrapper framework (Spring Kafka ConsumerFactory, Micronaut, Quarkus) is overriding or blanking group.id after you set it.

Example fix

// before
props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, brokers);
consumer = new AsyncKafkaConsumer<>(props, k, v);
consumer.commitSync(); // throws InvalidGroupIdException

// after
props.put(ConsumerConfig.GROUP_ID_CONFIG, "order-processor");
consumer = new AsyncKafkaConsumer<>(props, k, v);
consumer.commitSync();

Defensive patterns

Strategy: validation

Validate before calling

String groupId = props.getProperty(ConsumerConfig.GROUP_ID_CONFIG);
if (groupId == null || groupId.trim().isEmpty()) {
    throw new IllegalArgumentException("group.id must be set before using group management or offset commit APIs");
}
new KafkaConsumer<K, V>(props);

Try / catch

try {
    consumer.commitSync();
} catch (InvalidGroupIdException e) {
    // Configuration error: stop and fix consumer config rather than retrying.
    log.error("Consumer has no group.id; cannot use group APIs", e);
    throw e;
}

Prevention

Always set ConsumerConfig.GROUP_ID_CONFIG in the consumer properties when you intend to call subscribe(), commitSync(), commitAsync(), or committed().
If you only do manual assign() with no offset commits, an empty group.id is acceptable — otherwise it must be non-empty.
Centralize consumer construction behind a factory that validates required configs (group.id, bootstrap.servers, key/value deserializer) before instantiating KafkaConsumer.

When it happens

Trigger: Calling commitSync(), commitAsync(), committed(...), position(...) in group mode, groupMetadata(), or any rebalance-sensitive API on an AsyncKafkaConsumer constructed without setting group.id (or with group.id = null/empty, including group.protocol=consumer). The guard fires on the application thread inside acquireAndEnsureOpen before any network request is made.

Common situations: Migrating from LegacyKafkaConsumer to the new async consumer (group.protocol=consumer) and reusing an old properties bag that omitted group.id; using a consumer purely for admin-style lookups (offsetsForTimes, endOffsets) but then accidentally calling commit; setting group.instance.id or other group configs while forgetting the mandatory group.id; Spring/Kafka template configs that default group.id to null for manual assignment use cases.

Related errors

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