{"record":{"id":"39b2bc71338f45a5","repo":"apache/pulsar","slug":"sequence-subscriptions-not-supported-by-this-store","errorCode":null,"errorMessage":"Sequence subscriptions not supported by this store","messagePattern":"Sequence subscriptions not supported by this store","errorType":"exception","errorClass":"MetadataStoreException","httpStatus":null,"severity":"error","filePath":"pulsar-metadata/src/main/java/org/apache/pulsar/metadata/api/MetadataStore.java","lineNumber":448,"sourceCode":"     * <p>The {@code listener} receives the latest assigned sequence key (the full path with\n     * sequence suffix) as new sequence records are created under {@code prefix}. Multiple updates\n     * may be collapsed into a single event with the highest sequence — callers must treat the\n     * stream as monotonic but not exhaustive.\n     *\n     * <p>Closing the returned handle unsubscribes. On Oxia this delegates to the native\n     * sequence-update channel; other backends synthesize the stream from change notifications on\n     * the prefix's parent path.\n     *\n     * @param prefix   the sequence-key prefix (the same string passed as {@code path} to a\n     *                 {@code put} with {@link Option.SequenceKeysDeltas})\n     * @param listener callback receiving the full path of the latest sequence key\n     * @param opts     the set of {@link Option options} for this subscription\n     * @return a handle whose {@link AutoCloseable#close} cancels the subscription\n     * @throws MetadataStoreException if the store doesn't support sequence subscriptions\n     */\n    default AutoCloseable subscribeSequence(String prefix, Consumer<String> listener, Set<Option> opts)\n            throws MetadataStoreException {\n        throw new MetadataStoreException(\"Sequence subscriptions not supported by this store\");\n    }\n\n    /** Like {@link #subscribeSequence(String, Consumer, Set)} with no options. */\n    default AutoCloseable subscribeSequence(String prefix, Consumer<String> listener)\n            throws MetadataStoreException {\n        return subscribeSequence(prefix, listener, Set.of());\n    }\n\n    /**\n     * Returns the default metadata cache config.\n     *\n     * @return default metadata cache config\n     */\n    default MetadataCacheConfig<?> getDefaultMetadataCacheConfig() {\n        return MetadataCacheConfig.builder().build();\n    }\n}\n","sourceCodeStart":430,"sourceCodeEnd":466,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/api/MetadataStore.java#L430-L466","documentation":"MetadataStore.subscribeSequence(prefix, listener, opts) is a default interface method that throws MetadataStoreException('Sequence subscriptions not supported by this store'). Only stores implementing sequence (monotonic counter/delta) semantics override it; other backends (and mocks) reject the call with this exception.","triggerScenarios":"Calling subscribeSequence on a MetadataStore instance whose implementation (or a mock/test double) has not overridden the default method, e.g. calling it on a store backend that lacks sequence support.","commonSituations":"Using a metadata store backend that doesn't implement sequence subscriptions while running code that expects them (e.g. newer features built on sequence counters); unit tests with Mockito-mocked stores falling back to the interface default; older store implementations.","solutions":["Use a metadata store implementation that supports sequence subscriptions (e.g. the implementation in pulsar-metadata that overrides subscribeSequence).","Restructure the feature to fall back to plain get/put compare-and-set semantics when subscribeSequence throws MetadataStoreException.","In tests, stub subscribeSequence explicitly instead of relying on the interface default throwing.","Check feature/store compatibility matrix before enabling sequence-based features."],"exampleFix":"// before\nAutoCloseable handle = store.subscribeSequence(prefix, listener);\n// after\nAutoCloseable handle;\ntry {\n    handle = store.subscribeSequence(prefix, listener);\n} catch (MetadataStoreException e) {\n    handle = null;\n    log.warn(\"store {} lacks sequence subscriptions; using polling fallback\", store.name());\n    startPollingFallback(prefix, listener);\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    AutoCloseable h = store.subscribeSequence(prefix, listener, opts);\n} catch (MetadataStoreException e) {\n    log.warn(\"Sequence subscriptions unsupported on {}; using fallback\", store.name());\n    startPollingFallback(prefix, listener);\n}","preventionTips":["Verify store backend supports sequence subscriptions before enabling dependent features","In unit tests, explicitly stub subscribeSequence rather than relying on interface defaults","Design consumers of MetadataStore APIs with a non-sequence fallback path"],"tags":["pulsar-metadata","metadata-store","unsupported-operation","sequence"],"backgroundTag":"method-not-implemented","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}