{"id":"5238966def7a3de4","repo":"apache/kafka","slug":"the-configured-group-id-should-not-be-an-empty-str-523896","errorCode":null,"errorMessage":"The configured group.id should not be an empty string or whitespace.","messagePattern":"The configured group\\.id should not be an empty string or whitespace\\.","errorType":"exception","errorClass":"org.apache.kafka.common.errors.InvalidGroupIdException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/ClassicKafkaConsumer.java","lineNumber":162,"sourceCode":"    private final List<ConsumerPartitionAssignor> assignors;\n    // Init value is needed to avoid NPE in case of exception raised in the constructor\n    private Optional<ClientTelemetryReporter> clientTelemetryReporter = Optional.empty();\n\n    // currentThread holds the threadId of the current thread accessing this Consumer\n    // and is used to prevent multi-threaded access\n    private final AtomicLong currentThread = new AtomicLong(NO_CURRENT_THREAD);\n    // refcount is used to allow reentrant access by the thread who has acquired currentThread\n    private final AtomicInteger refcount = new AtomicInteger(0);\n\n    // to keep from repeatedly scanning subscriptions in poll(), cache the result during metadata updates\n    private boolean cachedSubscriptionHasAllFetchPositions;\n\n    ClassicKafkaConsumer(ConsumerConfig config, Deserializer<K> keyDeserializer, Deserializer<V> valueDeserializer) {\n        try {\n            GroupRebalanceConfig groupRebalanceConfig = new GroupRebalanceConfig(config,\n                    GroupRebalanceConfig.ProtocolType.CONSUMER);\n            if (groupRebalanceConfig.groupId != null && groupRebalanceConfig.groupId.isEmpty()) {\n                throw new InvalidGroupIdException(\"The configured \" + ConsumerConfig.GROUP_ID_CONFIG\n                        + \" should not be an empty string or whitespace.\");\n            }\n\n            this.groupId = Optional.ofNullable(groupRebalanceConfig.groupId);\n            this.clientId = config.getString(CommonClientConfigs.CLIENT_ID_CONFIG);\n            LogContext logContext = createLogContext(config, groupRebalanceConfig);\n            this.log = logContext.logger(getClass());\n            boolean enableAutoCommit = config.getBoolean(ENABLE_AUTO_COMMIT_CONFIG);\n\n            log.debug(\"Initializing the Kafka consumer\");\n            this.requestTimeoutMs = config.getInt(ConsumerConfig.REQUEST_TIMEOUT_MS_CONFIG);\n            this.defaultApiTimeoutMs = config.getInt(ConsumerConfig.DEFAULT_API_TIMEOUT_MS_CONFIG);\n            this.time = Time.SYSTEM;\n            List<MetricsReporter> reporters = CommonClientConfigs.metricsReporters(clientId, config);\n            this.clientTelemetryReporter = CommonClientConfigs.telemetryReporter(clientId, config);\n            this.clientTelemetryReporter.ifPresent(reporters::add);\n            this.metrics = createMetrics(config, time, reporters);\n            this.retryBackoffMs = config.getLong(ConsumerConfig.RETRY_BACKOFF_MS_CONFIG);","sourceCodeStart":144,"sourceCodeEnd":180,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/ClassicKafkaConsumer.java#L144-L180","documentation":"Thrown by the ClassicKafkaConsumer constructor as an InvalidGroupIdException when group.id is non-null but empty or whitespace. The config parser turns a missing group.id into null (treated as the default/no-group standalone consumer), but an explicit empty string cannot be a valid group identifier, so construction fails fast. This keeps callers from accidentally joining a group with an unusable id, which would otherwise cause coordinator failures later.","triggerScenarios":"Setting group.id=\"\" or group.id=\"   \" in consumer properties; a placeholder like group.id=${KAFKA_GROUP:} where the env var default resolves to empty; Spring Boot's spring.kafka.consumer.group-id bound to an empty property; reading group.id from a YAML key that is present but blank.","commonSituations":"Environment-variable templating that produces an empty string when the variable is unset; container/secret-injection that writes group.id= into a properties file; test configs that blank out group.id to 'disable' grouping (use null instead); copy-paste configs between services without updating the group id.","solutions":["Set group.id to a concrete non-empty value, e.g. group.id=order-service-consumer.","If you intend to run without consumer-group coordination, omit group.id entirely (or set it explicitly to null) rather than blank.","Audit property templating: use a default that is non-empty, e.g. group.id=${KAFKA_GROUP:order-service}, and fail startup if the resolved value is blank.","For Spring Boot, set spring.kafka.consumer.group-id to a real value or remove the property so the framework does not pass an empty string."],"exampleFix":"# before\ngroup.id=\n\n# after\ngroup.id=order-service-consumer","handlingStrategy":"validation","validationCode":"// Validate group.id before constructing the consumer.\nString groupId = props.getProperty(ConsumerConfig.GROUP_ID_CONFIG);\nif (groupId == null || groupId.trim().isEmpty()) {\n    throw new IllegalArgumentException(\n        ConsumerConfig.GROUP_ID_CONFIG + \" must be a non-empty, non-whitespace string\");\n}\nnew KafkaConsumer<K,V>(props);","typeGuard":"// Static helper that returns a sanitized group.id or fails fast.\nstatic String requireGroupId(Properties p) {\n    String g = p.getProperty(ConsumerConfig.GROUP_ID_CONFIG);\n    if (g == null || g.trim().isEmpty())\n        throw new IllegalArgumentException(\"group.id is blank\");\n    return g;\n}","tryCatchPattern":"try {\n    consumer = new KafkaConsumer<K,V>(props);\n} catch (org.apache.kafka.common.errors.InvalidGroupIdException e) {\n    log.error(\"group.id misconfigured; falling back to default\", e);\n    props.setProperty(ConsumerConfig.GROUP_ID_CONFIG, defaultGroupId);\n    consumer = new KafkaConsumer<K,V>(props);\n}","preventionTips":["Load group.id from a single validated config source (env var / KDL / properties) with a startup assertion.","Trim and check non-empty in your config loader, not deep inside Kafka client construction.","For standalone consumers with no group, explicitly set group.override.strategy or use assign() instead of subscribe().","Add an integration test that the app fails fast when group.id is missing."],"tags":["kafka","consumer","classic-consumer","configuration","group-id","validation"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}