{"record":{"id":"b6c7636f89f0fa81","repo":"apache/pulsar","slug":"e-getcause","errorCode":null,"errorMessage":"${e.getCause()}","messagePattern":"\\$\\{e\\.getCause\\(\\)\\}","errorType":"exception","errorClass":"org.apache.pulsar.client.impl.v5.PulsarClientException","httpStatus":null,"severity":"error","filePath":"pulsar-client-v5/src/main/java/org/apache/pulsar/client/impl/v5/QueueConsumerBuilderV5.java","lineNumber":72,"sourceCode":"     * one-per-segment design, which would also reject {@code topic://} scalable DLQ\n     * targets).\n     */\n    private DeadLetterPolicy dlqPolicy;\n\n    QueueConsumerBuilderV5(PulsarClientV5 client, Schema<T> v5Schema) {\n        this.client = client;\n        this.v5Schema = v5Schema;\n    }\n\n    @Override\n    public QueueConsumer<T> subscribe() throws PulsarClientException {\n        try {\n            return subscribeAsync().join();\n        } catch (java.util.concurrent.CompletionException e) {\n            if (e.getCause() instanceof PulsarClientException pce) {\n                throw pce;\n            }\n            throw new PulsarClientException(e.getCause());\n        }\n    }\n\n    @Override\n    public CompletableFuture<QueueConsumer<T>> subscribeAsync() {\n        boolean topicSet = topicName != null && !topicName.isEmpty();\n        boolean namespaceSet = namespaceName != null;\n        if (topicSet == namespaceSet) {\n            return CompletableFuture.failedFuture(\n                    new PulsarClientException.InvalidConfigurationException(\n                            \"Exactly one of .topic(name) or .namespace(...) must be set\"));\n        }\n        if (conf.getSubscriptionName() == null || conf.getSubscriptionName().isEmpty()) {\n            return CompletableFuture.failedFuture(\n                    new PulsarClientException.InvalidConfigurationException(\"Subscription name is required\"));\n        }\n\n        if (namespaceSet) {","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-v5/src/main/java/org/apache/pulsar/client/impl/v5/QueueConsumerBuilderV5.java#L54-L90","documentation":"The synchronous subscribe() joins subscribeAsync(); a CompletionException from the join is unwrapped — if the cause is a PulsarClientException it is re-thrown as-is, otherwise it is wrapped in a new PulsarClientException whose message is the cause's toString (${e.getCause()}). It indicates the subscription of the queue consumer failed for a reason outside the normal PulsarClientException set (e.g. schema/serializer failure, runtime error in builder internals).","triggerScenarios":"Calling QueueConsumerBuilderV5.subscribe() when the async subscription completes exceptionally: invalid combination of builder options (topic/subscription validation failure throwing a non-PulsarClientException like IllegalStateException), schema errors, or broker connection failures that arrive wrapped.","commonSituations":"Forgetting to set a topic or subscription name before subscribe(); using a schema incompatible with existing topic data; misconfigured dead-letter/retry options; broker down or authorization rejected.","solutions":["Read the wrapped cause (printed in the message) to identify the non-standard failure","Verify the builder state: topicName set, subscriptionName set, schema provided and matching the topic","Fix the root cause and retry subscribe(); route broker-level failures to standard PulsarClientException handling"],"exampleFix":"// before\nQueueConsumer<String> c = client.newConsumer(Schema.STRING).subscribe(); // topic never set\n// after\nQueueConsumer<String> c = client.newConsumer(Schema.STRING)\n    .topic(\"persistent://public/default/my-topic\")\n    .subscriptionName(\"my-sub\")\n    .subscribe();","handlingStrategy":"validation","validationCode":"if (topicName == null || topicName.isBlank()) throw new IllegalStateException(\"topic must be set before subscribe\");\nif (subscriptionName == null || subscriptionName.isBlank()) throw new IllegalStateException(\"subscriptionName must be set before subscribe\");","typeGuard":null,"tryCatchPattern":"try {\n    QueueConsumer<T> c = builder.subscribe();\n} catch (PulsarClientException e) {\n    log.error(\"Subscribe failed: {}\", e.getMessage(), e.getCause());\n}","preventionTips":["Set topic and subscriptionName before calling subscribe()","Ensure the schema matches the topic's existing data","Subscribe at startup where failures are visible, not lazily on first message"],"tags":["consumer","subscription","builder"],"backgroundTag":"subscription-failed","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"}