{"id":"2382712a315bde51","repo":"apache/kafka","slug":"to-use-the-group-management-or-offset-commit-apis-238271","errorCode":null,"errorMessage":"To use the group management or offset commit APIs, you must provide a valid {} in the consumer configuration.","messagePattern":"To use the group management or offset commit APIs, you must provide a valid (.+?) in the consumer configuration\\.","errorType":"exception","errorClass":"InvalidGroupIdException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/ClassicKafkaConsumer.java","lineNumber":1280,"sourceCode":"    }\n\n    /**\n     * Release the light lock protecting the consumer from multi-threaded access.\n     */\n    private void release() {\n        if (refcount.decrementAndGet() == 0)\n            currentThread.set(NO_CURRENT_THREAD);\n    }\n\n    private void throwIfNoAssignorsConfigured() {\n        if (assignors.isEmpty())\n            throw new IllegalStateException(\"Must configure at least one partition assigner class name to \" +\n                    ConsumerConfig.PARTITION_ASSIGNMENT_STRATEGY_CONFIG + \" configuration property\");\n    }\n\n    private void throwIfGroupIdNotDefined() {\n        if (groupId.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    private void updateLastSeenEpochIfNewer(TopicPartition topicPartition, OffsetAndMetadata offsetAndMetadata) {\n        if (offsetAndMetadata != null)\n            offsetAndMetadata.leaderEpoch().ifPresent(epoch -> metadata.updateLastSeenEpochIfNewer(topicPartition, epoch));\n    }\n\n    // Functions below are for testing only\n    @Override\n    public String clientId() {\n        return clientId;\n    }\n\n    @Override\n    public Metrics metricsRegistry() {\n        return metrics;\n    }","sourceCodeStart":1262,"sourceCodeEnd":1298,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/ClassicKafkaConsumer.java#L1262-L1298","documentation":"InvalidGroupIdException thrown by ClassicKafkaConsumer.throwIfGroupIdNotDefined() (ClassicKafkaConsumer.java:1278) when an operation that requires group membership is invoked while group.id is null or empty. Group-based subscription, offset commit, and offset-fetch all depend on a valid group.id; without one the coordinator cannot track the member, so the client fails fast at the API boundary.","triggerScenarios":"Calling subscribe(Collection), subscribe(Pattern), commitSync, commitAsync, committed, listConsumerGroupOffsets, or any group-metadata API on a consumer with no group.id. The check is reached from throwIfGroupIdNotDefined callsites at ClassicKafkaConsumer.java:494, 575, 759, 785, 906, 1077.","commonSituations":"Migrating from manual assign() usage to subscribe() without adding group.id; property key typo (group instead of group.id); env var (GROUP_ID) not exported in the runtime environment; a thin wrapper or framework that strips unknown keys; intentionally blank group.id during local testing.","solutions":["Set group.id to a non-empty, stable string in the consumer config.","If manual assignment is the intent, call assign(Collection<TopicPartition>) instead of subscribe(...) and do not call commit APIs.","Verify the exact property key (group.id) and that no later config layer is overriding it to empty."],"exampleFix":"// before\nprops.put(\"group\", \"orders\");                  // typo, ignored\nconsumer.subscribe(Arrays.asList(\"orders\"));     // throws InvalidGroupIdException\n\n// after\nprops.put(ConsumerConfig.GROUP_ID_CONFIG, \"order-processor\");\nconsumer.subscribe(Arrays.asList(\"orders\"));","handlingStrategy":"validation","validationCode":"// Validate group.id is present before any group-management API\nString groupId = props.getProperty(ConsumerConfig.GROUP_ID_CONFIG);\nboolean willUseGroupApi = subscribeMode || commitRequested;\nif (willUseGroupApi && (groupId == null || groupId.trim().isEmpty())) {\n    throw new IllegalArgumentException(\n        \"group.id must be set to use subscribe() or commit*\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    consumer.subscribe(topics);\n} catch (InvalidGroupIdException e) {\n    // set group.id, recreate the consumer, then retry subscribe\n}","preventionTips":["Always set a non-empty group.id when calling subscribe() or commitSync()/commitAsync().","If you do not want a group, use assign() for manual partition assignment and track offsets yourself.","Treat an unset/blank group.id as a fatal configuration error at startup."],"tags":["configuration","consumer","group-id"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}