{"record":{"id":"a274273c4ced1b3f","repo":"apache/pulsar","slug":"autoscaledreceiverqueuesize-is-not-supported-in-ze","errorCode":null,"errorMessage":"AutoScaledReceiverQueueSize is not supported in ZeroQueueConsumerImpl","messagePattern":"AutoScaledReceiverQueueSize is not supported in ZeroQueueConsumerImpl","errorType":"exception","errorClass":"NotImplementedException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/ZeroQueueConsumerImpl.java","lineNumber":65,"sourceCode":"    public ZeroQueueConsumerImpl(PulsarClientImpl client, String topic, ConsumerConfigurationData<T> conf,\n             ExecutorProvider executorProvider, int partitionIndex, boolean hasParentConsumer,\n             CompletableFuture<Consumer<T>> subscribeFuture, MessageId startMessageId, Schema<T> schema,\n             ConsumerInterceptors<T> interceptors,\n             boolean createTopicIfDoesNotExist) {\n        super(client, topic, conf, executorProvider, partitionIndex, hasParentConsumer, false, subscribeFuture,\n                startMessageId, 0 /* startMessageRollbackDurationInSec */, schema, interceptors,\n                createTopicIfDoesNotExist);\n    }\n\n    @Override\n    public int minReceiverQueueSize() {\n        return 0;\n    }\n\n    @Override\n    public void initReceiverQueueSize() {\n        if (conf.isAutoScaledReceiverQueueSizeEnabled()) {\n            throw new NotImplementedException(\"AutoScaledReceiverQueueSize is not supported in ZeroQueueConsumerImpl\");\n        } else {\n            CURRENT_RECEIVER_QUEUE_SIZE_UPDATER.set(this, 0);\n        }\n    }\n\n    @Override\n    protected Message<T> internalReceive() throws PulsarClientException {\n        zeroQueueLock.lock();\n        try {\n            Message<T> msg = fetchSingleMessageFromBroker();\n            trackMessage(msg);\n            return beforeConsume(msg);\n        } finally {\n            zeroQueueLock.unlock();\n        }\n    }\n\n    @Override","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/ZeroQueueConsumerImpl.java#L47-L83","documentation":"ZeroQueueConsumerImpl.initReceiverQueueSize() throws NotImplementedException when auto-scaled receiver queue size is enabled on a consumer configured with receiverQueueSize=0. Zero-queue consumers have a fixed queue of 0 (fetch-per-message mode); the auto-scaled queue feature fundamentally requires a non-zero queue to scale, so combining them is rejected at consumer construction.","triggerScenarios":"Creating a consumer/reader with ConsumerBuilder.receiverQueueSize(0) (or conf receiverQueueSize=0) while autoScaledReceiverQueueSizeEnabled=true in the configuration data; the factory's initReceiverQueueSize() runs at construction and throws immediately.","commonSituations":"A shared ClientConfigurationData enables auto-scaled receiver queue globally while some consumers/readers opt into zero queue size; readers with receiverQueueSize=0 for at-least-once semantics; configuration merges turning on the feature accidentally; MultiTopicsConsumer passing zero per-topic queue sizes.","solutions":["Disable autoScaledReceiverQueueSizeEnabled in the configuration when using zero-queue consumers.","Remove receiverQueueSize(0) (use a positive size) if auto-scaling is desired.","Guard construction: only enable auto-scaled queue when conf.getReceiverQueueSize() > 0."],"exampleFix":"// before\nclient.newConsumer().receiverQueueSize(0) // conf.autoScaledReceiverQueueSizeEnabled=true -> throws\n// after\nclient.newConsumer().receiverQueueSize(0)\n      .loadConf(Map.of(\"autoScaledReceiverQueueSizeEnabled\", false));","handlingStrategy":"validation","validationCode":"if (conf.getReceiverQueueSize() == 0 && conf.isAutoScaledReceiverQueueSizeEnabled()) {\n    throw new IllegalArgumentException(\"autoScaledReceiverQueueSize cannot be used with receiverQueueSize=0\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Consumer<T> c = client.newConsumer()...subscribe();\n} catch (NotImplementedException e) {\n    log.error(\"incompatible consumer options: {}\", e.getMessage());\n    throw e;\n}","preventionTips":["Never combine receiverQueueSize=0 with autoScaledReceiverQueueSizeEnabled=true.","Gate the auto-scaled flag on a positive receiver queue size in shared config code.","Document that zero-queue consumers are fetch-per-message and cannot auto-scale."],"tags":["java","consumer","configuration","pulsar-client"],"backgroundTag":"unsupported-feature-combination","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"}