{"id":"4c875c55281c1c7a","repo":"apache/kafka","slug":"tried-to-force-a-rebalance-but-consumer-does-not-h","errorCode":null,"errorMessage":"Tried to force a rebalance but consumer does not have a group.","messagePattern":"Tried to force a rebalance but consumer does not have a group\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"clients/src/main/java/org/apache/kafka/clients/consumer/internals/ClassicKafkaConsumer.java","lineNumber":1089,"sourceCode":"    }\n\n    @Override\n    public ConsumerGroupMetadata groupMetadata() {\n        acquireAndEnsureOpen();\n        try {\n            throwIfGroupIdNotDefined();\n            return coordinator.groupMetadata();\n        } finally {\n            release();\n        }\n    }\n\n    @Override\n    public void enforceRebalance(final String reason) {\n        acquireAndEnsureOpen();\n        try {\n            if (coordinator == null) {\n                throw new IllegalStateException(\"Tried to force a rebalance but consumer does not have a group.\");\n            }\n            coordinator.requestRejoin(reason == null || reason.isEmpty() ? DEFAULT_REASON : reason);\n        } finally {\n            release();\n        }\n    }\n\n    @Override\n    public void enforceRebalance() {\n        enforceRebalance(null);\n    }\n\n    @Override\n    public void close() {\n        close(CloseOptions.timeout(Duration.ofMillis(DEFAULT_CLOSE_TIMEOUT_MS)));\n    }\n\n    @Deprecated","sourceCodeStart":1071,"sourceCodeEnd":1107,"githubUrl":"https://github.com/apache/kafka/blob/c31c9215e131f8c17e79f8901b48c13ee6aa8e7a/clients/src/main/java/org/apache/kafka/clients/consumer/internals/ClassicKafkaConsumer.java#L1071-L1107","documentation":"Thrown by KafkaConsumer.enforceRebalance(...) when the consumer has no group coordinator, i.e. group.id is not set (or coordinator was never created). enforceRebalance only makes sense for consumers participating in a group; without one there is nothing to rejoin, so the call is invalid. This is a client-side check before any network interaction.","triggerScenarios":"Calling consumer.enforceRebalance() on a consumer built with assign() (manual assignment, no group.id); calling it when group.id is null or empty; using enforceRebalance in a standalone consumer to 'refresh'.","commonSituations":"Generic utility code that always calls enforceRebalance regardless of subscribe vs assign; misconfigured deployments missing group.id; copying code from a subscribing consumer into an assigning one.","solutions":["Only call enforceRebalance() on consumers that use subscribe() with a group.id.","Set group.id in consumer config if you intend to participate in a group and force rejoin.","Remove the call from manual-assignment (assign()) code paths; manual assignment does not rebalance."],"exampleFix":"// before (manual assignment)\nconsumer.assign(List.of(tp));\nconsumer.enforceRebalance(); // throws\n\n// after - remove the call for assign()-based consumers\nconsumer.assign(List.of(tp));\n// or, if you want rebalances, switch to subscribe:\n// props.put(ConsumerConfig.GROUP_ID_CONFIG, \"g1\");\n// consumer.subscribe(List.of(\"topic\"));","handlingStrategy":"validation","validationCode":"// enforceRebalance() requires a group; skip it for assign() (no-group) consumers:\nif (groupId != null && !groupId.isEmpty()) {\n    consumer.enforceRebalance(\"operator-triggered\");\n} else {\n    log.debug(\"Skipping enforceRebalance: consumer has no group (manual assignment)\");\n}","typeGuard":"// Distinguish grouped vs standalone consumers at the type level:\nsealed interface KafkaClient permits GroupedConsumer, StandaloneConsumer {}\nfinal class GroupedConsumer {\n    final String groupId;\n    void enforceRebalance(String reason) { /* delegate */ }\n}\nfinal class StandaloneConsumer {\n    // no enforceRebalance method exists at all — the call site won't compile\n}","tryCatchPattern":"// Only swallow this specific misconfiguration; let other IllegalState exceptions propagate:\ntry {\n    consumer.enforceRebalance();\n} catch (IllegalStateException e) {\n    if (!e.getMessage().contains(\"does not have a group\")) throw e;\n    log.info(\"enforceRebalance ignored: standalone consumer\");\n}","preventionTips":["Gate every enforceRebalance() call behind the same condition that decided assign() vs subscribe() — if you don't have a group, you can't rebalance.","Keep group membership a single, explicit flag in your consumer factory so call sites can branch on it without guessing.","Don't call enforceRebalance() defensively in a shutdown hook; closing a standalone consumer will already do the right thing."],"tags":["consumer","rebalance","config","java"],"analyzedSha":"c31c9215e131f8c17e79f8901b48c13ee6aa8e7a","analyzedAt":"2026-08-03T12:34:05.770Z","schemaVersion":2}