apache/pulsar · error · MetadataStoreException

Sequence subscriptions not supported by this store

Error message

Sequence subscriptions not supported by this store

What it means

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.

Source

Thrown at pulsar-metadata/src/main/java/org/apache/pulsar/metadata/api/MetadataStore.java:448

     * <p>The {@code listener} receives the latest assigned sequence key (the full path with
     * sequence suffix) as new sequence records are created under {@code prefix}. Multiple updates
     * may be collapsed into a single event with the highest sequence — callers must treat the
     * stream as monotonic but not exhaustive.
     *
     * <p>Closing the returned handle unsubscribes. On Oxia this delegates to the native
     * sequence-update channel; other backends synthesize the stream from change notifications on
     * the prefix's parent path.
     *
     * @param prefix   the sequence-key prefix (the same string passed as {@code path} to a
     *                 {@code put} with {@link Option.SequenceKeysDeltas})
     * @param listener callback receiving the full path of the latest sequence key
     * @param opts     the set of {@link Option options} for this subscription
     * @return a handle whose {@link AutoCloseable#close} cancels the subscription
     * @throws MetadataStoreException if the store doesn't support sequence subscriptions
     */
    default AutoCloseable subscribeSequence(String prefix, Consumer<String> listener, Set<Option> opts)
            throws MetadataStoreException {
        throw new MetadataStoreException("Sequence subscriptions not supported by this store");
    }

    /** Like {@link #subscribeSequence(String, Consumer, Set)} with no options. */
    default AutoCloseable subscribeSequence(String prefix, Consumer<String> listener)
            throws MetadataStoreException {
        return subscribeSequence(prefix, listener, Set.of());
    }

    /**
     * Returns the default metadata cache config.
     *
     * @return default metadata cache config
     */
    default MetadataCacheConfig<?> getDefaultMetadataCacheConfig() {
        return MetadataCacheConfig.builder().build();
    }
}

View on GitHub (pinned to 820761864e)

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.

Example fix

// before
AutoCloseable handle = store.subscribeSequence(prefix, listener);
// after
AutoCloseable handle;
try {
    handle = store.subscribeSequence(prefix, listener);
} catch (MetadataStoreException e) {
    handle = null;
    log.warn("store {} lacks sequence subscriptions; using polling fallback", store.name());
    startPollingFallback(prefix, listener);
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    AutoCloseable h = store.subscribeSequence(prefix, listener, opts);
} catch (MetadataStoreException e) {
    log.warn("Sequence subscriptions unsupported on {}; using fallback", store.name());
    startPollingFallback(prefix, listener);
}

Prevention

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

When it happens

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

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

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/39b2bc71338f45a5. Report an issue: GitHub.