apache/kafka · error · 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 {} in the consumer configuration.

What it means

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.

Source

Thrown at clients/src/main/java/org/apache/kafka/clients/consumer/internals/ClassicKafkaConsumer.java:1280

    }

    /**
     * Release the light lock protecting the consumer from multi-threaded access.
     */
    private void release() {
        if (refcount.decrementAndGet() == 0)
            currentThread.set(NO_CURRENT_THREAD);
    }

    private void throwIfNoAssignorsConfigured() {
        if (assignors.isEmpty())
            throw new IllegalStateException("Must configure at least one partition assigner class name to " +
                    ConsumerConfig.PARTITION_ASSIGNMENT_STRATEGY_CONFIG + " configuration property");
    }

    private void throwIfGroupIdNotDefined() {
        if (groupId.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.");
    }

    private void updateLastSeenEpochIfNewer(TopicPartition topicPartition, OffsetAndMetadata offsetAndMetadata) {
        if (offsetAndMetadata != null)
            offsetAndMetadata.leaderEpoch().ifPresent(epoch -> metadata.updateLastSeenEpochIfNewer(topicPartition, epoch));
    }

    // Functions below are for testing only
    @Override
    public String clientId() {
        return clientId;
    }

    @Override
    public Metrics metricsRegistry() {
        return metrics;
    }

View on GitHub (pinned to c31c9215e1)

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.

Example fix

// before
props.put("group", "orders");                  // typo, ignored
consumer.subscribe(Arrays.asList("orders"));     // throws InvalidGroupIdException

// after
props.put(ConsumerConfig.GROUP_ID_CONFIG, "order-processor");
consumer.subscribe(Arrays.asList("orders"));

Defensive patterns

Strategy: validation

Validate before calling

// Validate group.id is present before any group-management API
String groupId = props.getProperty(ConsumerConfig.GROUP_ID_CONFIG);
boolean willUseGroupApi = subscribeMode || commitRequested;
if (willUseGroupApi && (groupId == null || groupId.trim().isEmpty())) {
    throw new IllegalArgumentException(
        "group.id must be set to use subscribe() or commit*");
}

Try / catch

try {
    consumer.subscribe(topics);
} catch (InvalidGroupIdException e) {
    // set group.id, recreate the consumer, then retry subscribe
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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