{"record":{"id":"47eb23adc129d8ea","repo":"apache/pulsar","slug":"can-t-use-batch-receive-if-the-queue-size-is-0","errorCode":null,"errorMessage":"Can't use batch receive, if the queue size is 0","messagePattern":"Can't use batch receive, if the queue size is 0","errorType":"exception","errorClass":"PulsarClientException.InvalidConfigurationException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/ConsumerBase.java","lineNumber":1048,"sourceCode":"            case Closed:\n                throw  new PulsarClientException.AlreadyClosedException(\"Consumer already closed\");\n            case Terminated:\n                throw new PulsarClientException.AlreadyClosedException(\"Topic was terminated\");\n            case Failed:\n            case Uninitialized:\n                throw new PulsarClientException.NotConnectedException();\n            default:\n                break;\n        }\n    }\n\n    private void verifyBatchReceive() throws PulsarClientException {\n        if (listener != null) {\n            throw new PulsarClientException.InvalidConfigurationException(\n                \"Cannot use receive() when a listener has been set\");\n        }\n        if (getCurrentReceiverQueueSize() == 0) {\n            throw new PulsarClientException.InvalidConfigurationException(\n                \"Can't use batch receive, if the queue size is 0\");\n        }\n    }\n\n    protected static final class OpBatchReceive<T> {\n\n        final CompletableFuture<Messages<T>> future;\n        final long createdAt;\n\n        private OpBatchReceive(CompletableFuture<Messages<T>> future) {\n            this.future = future;\n            this.createdAt = System.nanoTime();\n        }\n\n        static <T> OpBatchReceive<T> of(CompletableFuture<Messages<T>> future) {\n            return new OpBatchReceive<>(future);\n        }\n    }","sourceCodeStart":1030,"sourceCodeEnd":1066,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/ConsumerBase.java#L1030-L1066","documentation":"batchReceive() requires a non-zero receiver queue size because the batch receive fills a collection from the consumer's internal queue; with receiverQueueSize=0 there is nowhere to buffer messages, so the client rejects the call up front with InvalidConfigurationException.","triggerScenarios":"Calling batchReceive() or batchReceiveAsync() on a consumer whose getCurrentReceiverQueueSize() is 0 — typically after ConsumerBuilder.receiverQueueSize(0) (often combined with a Key_Shared/exclusive pattern or memory-constrained setups).","commonSituations":"Setting receiverQueueSize(0) to get strict per-message ordering or low-latency behavior, then later adding batchReceive for throughput; copying configs between consumers.","solutions":["Set receiverQueueSize to a positive value (default 1000) in the ConsumerBuilder.","Use plain receive()/receiveAsync() instead of batchReceive() when the queue size must remain 0."],"exampleFix":"// before\nConsumer<byte[]> c = client.newConsumer().receiverQueueSize(0).subscribe();\nMessages<byte[]> msgs = c.batchReceive();\n// after\nConsumer<byte[]> c = client.newConsumer().receiverQueueSize(100).subscribe();\nMessages<byte[]> msgs = c.batchReceive();","handlingStrategy":"validation","validationCode":"if (consumer.getQueueSize() == 0) { /* use receive() instead of batchReceive() */ }","typeGuard":null,"tryCatchPattern":"try {\n  Messages<byte[]> msgs = consumer.batchReceive();\n} catch (PulsarClientException.InvalidConfigurationException e) {\n  // receiverQueueSize is 0: switch to receiveAsync()\n}","preventionTips":["Never combine receiverQueueSize(0) with batchReceive APIs.","Centralize consumer construction so queue-size and receive-mode stay consistent.","Default to the standard receiverQueueSize (1000) unless you have a specific reason."],"tags":["pulsar","consumer","batch-receive","configuration"],"backgroundTag":"invalid-consumer-configuration","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"}