apache/kafka · error · InvalidGroupIdException

The configured group.id should not be an empty string or…

Error message

The configured group.id should not be an empty string or whitespace.

What it means

AsyncKafkaConsumer.initializeGroupMetadata deliberately distinguishes null group.id (allowed - supports standalone/no-group consumers) from an empty/whitespace string, which is rejected with InvalidGroupIdException. An empty group id would otherwise create a group whose name cannot be addressed for admin operations or rebalances.

Solutions

1. Provide a non-empty group.id, or remove the key entirely to operate without a group.
2. If group.id comes from configuration/env, validate it is non-blank before constructing the consumer and fail fast with a clear message.
3. Use Objects.requireNonNullElseGet to fall back to a concrete id rather than "" when the source is unset.

Example fix

// before
props.put(ConsumerConfig.GROUP_ID_CONFIG, System.getenv().getOrDefault("KAFKA_GROUP", ""));
new KafkaConsumer<>(props); // -> InvalidGroupIdException when env unset

// after
String gid = System.getenv("KAFKA_GROUP");
if (gid != null && !gid.isBlank()) {
    props.put(ConsumerConfig.GROUP_ID_CONFIG, gid);
}
new KafkaConsumer<>(props);

String gid = props.getProperty(ConsumerConfig.GROUP_ID_CONFIG);
if (gid != null && gid.trim().isEmpty()) {
    throw new IllegalArgumentException(ConsumerConfig.GROUP_ID_CONFIG + " must be non-blank or omitted");
}

null

try { new KafkaConsumer<>(props); }
catch (InvalidGroupIdException e) { /* unset or fix group.id */ props.remove(ConsumerConfig.GROUP_ID_CONFIG); }

When it happens

Trigger: Constructing KafkaConsumer with group.id set to "" (empty) or a whitespace-only string - typically because a properties file or env var resolved to an empty value.

Common situations: group.id sourced from an unset env var (System.getenv returns null) that a wrapper defaulted to ""; Spring/Quarkus config binding an empty placeholder; YAML/properties with `group.id=` (no value).

Related errors

• enable.auto.commit cannot be set to true when default group…
• cannot be set when using a share group.
• Failed to construct kafka consumer
• Invalid negative offset
• Invalid negative offset

AI-assisted analysis of apache/kafka@996fb4585a (2026-08-11). Data as JSON: /api/errors/3e00469f5a5d8bba. Report an issue: GitHub.

Appendix: source

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

    private Optional<ConsumerGroupMetadata> initializeGroupMetadata(final ConsumerConfig config,
                                                                    final GroupRebalanceConfig groupRebalanceConfig) {
        final Optional<ConsumerGroupMetadata> groupMetadata = initializeGroupMetadata(
            groupRebalanceConfig.groupId,
            groupRebalanceConfig.groupInstanceId
        );
        if (groupMetadata.isEmpty()) {
            config.ignore(ConsumerConfig.AUTO_COMMIT_INTERVAL_MS_CONFIG);
            config.ignore(THROW_ON_FETCH_STABLE_OFFSET_UNSUPPORTED);
        }
        return groupMetadata;
    }

    private Optional<ConsumerGroupMetadata> initializeGroupMetadata(final String groupId,
                                                                    final Optional<String> groupInstanceId) {
        if (groupId != null) {
            if (groupId.isEmpty()) {
                throw new InvalidGroupIdException("The configured " + ConsumerConfig.GROUP_ID_CONFIG
                    + " should not be an empty string or whitespace.");
            } else {
                return Optional.of(initializeConsumerGroupMetadata(groupId, groupInstanceId));
            }
        }
        return Optional.empty();
    }

    @SuppressWarnings("removal")
    private ConsumerGroupMetadata initializeConsumerGroupMetadata(final String groupId,
                                                                  final Optional<String> groupInstanceId) {
        return new ConsumerGroupMetadata(
            groupId,
            JoinGroupRequest.UNKNOWN_GENERATION_ID,
            JoinGroupRequest.UNKNOWN_MEMBER_ID,
            groupInstanceId
        );
    }

View on GitHub (pinned to 996fb4585a)