{"id":"3c64367d6b803e52","repo":"apache/kafka","slug":"to-use-the-group-management-or-offset-commit-apis","errorCode":null,"errorMessage":"To use the group management or offset commit APIs, you must provide a valid group.id in the consumer configuration.","messagePattern":"To use the group management or offset commit APIs, you must provide a valid group\\.id in the consumer configuration\\.","errorType":"exception","errorClass":"org.apache.kafka.common.errors.InvalidGroupIdException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/AsyncKafkaConsumer.java","lineNumber":1293,"sourceCode":"            wakeupTrigger.setActiveTask(event.future());\n            try {\n                return applicationEventHandler.addAndGet(event);\n            } catch (TimeoutException e) {\n                throw new TimeoutException(\"Timeout of \" + timeout.toMillis() + \"ms expired before the last \" +\n                    \"committed offset for partitions \" + partitions + \" could be determined. Try tuning \" +\n                    ConsumerConfig.DEFAULT_API_TIMEOUT_MS_CONFIG + \" larger to relax the threshold.\");\n            } finally {\n                wakeupTrigger.clearTask();\n            }\n        } finally {\n            kafkaConsumerMetrics.recordCommitted(time.nanoseconds() - start);\n            release();\n        }\n    }\n\n    private void throwIfGroupIdNotDefined() {\n        if (groupMetadata.get().isEmpty()) {\n            throw new InvalidGroupIdException(\"To use the group management or offset commit APIs, you must \" +\n                \"provide a valid \" + ConsumerConfig.GROUP_ID_CONFIG + \" in the consumer configuration.\");\n        }\n    }\n\n    @Override\n    public Map<MetricName, ? extends Metric> metrics() {\n        return Collections.unmodifiableMap(metrics.metrics());\n    }\n\n    @Override\n    public List<PartitionInfo> partitionsFor(String topic) {\n        return partitionsFor(topic, defaultApiTimeoutMs);\n    }\n\n    @Override\n    public List<PartitionInfo> partitionsFor(String topic, Duration timeout) {\n        acquireAndEnsureOpen();\n        try {","sourceCodeStart":1275,"sourceCodeEnd":1311,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/AsyncKafkaConsumer.java#L1275-L1311","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nprops.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, brokers);\nconsumer = new AsyncKafkaConsumer<>(props, k, v);\nconsumer.commitSync(); // throws InvalidGroupIdException\n\n// after\nprops.put(ConsumerConfig.GROUP_ID_CONFIG, \"order-processor\");\nconsumer = new AsyncKafkaConsumer<>(props, k, v);\nconsumer.commitSync();","handlingStrategy":"validation","validationCode":"String groupId = props.getProperty(ConsumerConfig.GROUP_ID_CONFIG);\nif (groupId == null || groupId.trim().isEmpty()) {\n    throw new IllegalArgumentException(\"group.id must be set before using group management or offset commit APIs\");\n}\nnew KafkaConsumer<K, V>(props);","typeGuard":null,"tryCatchPattern":"try {\n    consumer.commitSync();\n} catch (InvalidGroupIdException e) {\n    // Configuration error: stop and fix consumer config rather than retrying.\n    log.error(\"Consumer has no group.id; cannot use group APIs\", e);\n    throw e;\n}","preventionTips":["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."],"tags":["kafka","consumer","configuration","group-management"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}