{"record":{"id":"94d951c381510034","repo":"apache/pulsar","slug":"invalid-key-shared-mode-keysharedmode-94d951","errorCode":null,"errorMessage":"Invalid key-shared mode: ${keySharedMode}","messagePattern":"Invalid key-shared mode: (.+?)","errorType":"validation","errorClass":"java.lang.IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/service/persistent/PersistentStickyKeyDispatcherMultipleConsumersClassic.java","lineNumber":140,"sourceCode":"        switch (this.keySharedMode) {\n        case AUTO_SPLIT:\n            if (conf.isSubscriptionKeySharedUseConsistentHashing()) {\n                selector = new ConsistentHashingStickyKeyConsumerSelector(\n                        conf.getSubscriptionKeySharedConsistentHashingReplicaPoints(),\n                        false,\n                        // Classic implementation uses Integer.MAX_VALUE - 1 as the range end value\n                        Integer.MAX_VALUE - 1);\n            } else {\n                selector = new HashRangeAutoSplitStickyKeyConsumerSelector();\n            }\n            break;\n\n        case STICKY:\n            this.selector = new HashRangeExclusiveStickyKeyConsumerSelector();\n            break;\n\n        default:\n            throw new IllegalArgumentException(\"Invalid key-shared mode: \" + keySharedMode);\n        }\n    }\n\n    @VisibleForTesting\n    public StickyKeyConsumerSelector getSelector() {\n        return selector;\n    }\n\n    @Override\n    public synchronized CompletableFuture<Void> addConsumer(Consumer consumer) {\n        if (IS_CLOSED_UPDATER.get(this) == TRUE) {\n            log.warn()\n                    .attr(\"consumer\", consumer)\n                    .log(\"Dispatcher is already closed. Closing consumer\");\n            consumer.disconnect();\n            return CompletableFuture.completedFuture(null);\n        }\n        return super.addConsumer(consumer).thenCompose(__ ->","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/service/persistent/PersistentStickyKeyDispatcherMultipleConsumersClassic.java#L122-L158","documentation":"When a Key_Shared subscription dispatcher is created, the broker instantiates a StickyKeyConsumerSelector based on the subscription's KeySharedMode. Only STICKY and AUTO_SPLIT selectors are implemented; any other mode value falls into the default branch and throws IllegalArgumentException. This is a defensive guard against unsupported/unknown KeySharedMode enum values reaching the dispatcher constructor.","triggerScenarios":"Creating a PersistentStickyKeyDispatcherMultipleConsumersClassic for a Key_Shared subscription whose KeySharedMode is neither AUTO_SPLIT nor STICKY — typically when a policy/store contains a newer enum value (e.g. from a newer broker/client version) that the classic dispatcher implementation does not support, or corrupted subscription properties.","commonSituations":"Clusters with mixed broker versions where a topic's KeySharedMode was set by a newer broker, then handled by a broker running subscriptionKeySharedUseClassicImplementation=true; hand-edited or migrated topic policy data; client producers/consumers negotiating a mode the classic dispatcher predates.","solutions":["Disable the classic implementation (remove subscriptionKeySharedUseClassicImplementation=true or set it to false) so the modern KeyShared dispatcher handles the mode","Align broker versions across the cluster so all brokers support the KeySharedMode in use","Check the subscription's policies and explicitly set KeySharedMode to STICKY or AUTO_SPLIT (e.g. via setSubscriptionKeySharedType on the admin API)","Clear/repair the subscription policy data if it contains an unknown mode value"],"exampleFix":"// before (broker.conf)\nsubscriptionKeySharedUseClassicImplementation=true\n// after (broker.conf)\nsubscriptionKeySharedUseClassicImplementation=false","handlingStrategy":"validation","validationCode":"KeySharedMode mode = policies.getKeySharedMode();\nif (mode != KeySharedMode.AUTO_SPLIT && mode != KeySharedMode.STICKY) {\n    throw new IllegalArgumentException(\"Unsupported KeySharedMode for classic dispatcher: \" + mode);\n}","typeGuard":"boolean isSupportedKeySharedMode(KeySharedMode m) {\n    return m == KeySharedMode.AUTO_SPLIT || m == KeySharedMode.STICKY;\n}","tryCatchPattern":"try {\n    dispatcher = new PersistentStickyKeyDispatcherMultipleConsumersClassic(...);\n} catch (IllegalArgumentException e) {\n    log.error(\"KeyShared dispatcher creation failed: {}\", e.getMessage());\n    // fall back to non-classic dispatcher or fail subscription setup\n}","preventionTips":["Do not enable subscriptionKeySharedUseClassicImplementation in clusters running brokers with newer KeySharedMode values","Pin all brokers to the same Pulsar version","Always set KeySharedMode explicitly to STICKY or AUTO_SPLIT in topic policies"],"tags":["pulsar","broker","key-shared","subscription","illegal-argument"],"backgroundTag":"invalid-key-shared-mode","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}