{"record":{"id":"0fa08506aa6c6ac8","repo":"apache/pulsar","slug":"cause-0fa085","errorCode":null,"errorMessage":"${cause}","messagePattern":"\\$\\{cause\\}","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/ProducerBuilderV5.java","lineNumber":65,"sourceCode":"\n    ProducerBuilderV5(PulsarClientV5 client, Schema<T> v5Schema) {\n        this.client = client;\n        this.v5Schema = v5Schema;\n    }\n\n    @Override\n    public Producer<T> create() throws PulsarClientException {\n        try {\n            return createAsync().join();\n        } catch (java.util.concurrent.CompletionException e) {\n            Throwable cause = e.getCause();\n            if (cause instanceof PulsarClientException pce) {\n                throw pce;\n            }\n            if (cause instanceof org.apache.pulsar.client.api.PulsarClientException.NotFoundException) {\n                throw new PulsarClientException.NotFoundException(cause.getMessage());\n            }\n            throw new PulsarClientException(cause);\n        }\n    }\n\n    @Override\n    public CompletableFuture<Producer<T>> createAsync() {\n        String topicStr = conf.getTopicName();\n        if (topicStr == null || topicStr.isEmpty()) {\n            return CompletableFuture.failedFuture(\n                    new PulsarClientException.InvalidConfigurationException(\"Topic name is required\"));\n        }\n\n        TopicName topicName = V5Utils.parseScalableTopicInput(topicStr);\n\n        // Create DAG watch client and start the session\n        DagWatchClient dagWatch = new DagWatchClient(client.v4Client(), topicName);\n\n        return dagWatch.start()\n                .thenCompose(initialLayout -> {","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-v5/src/main/java/org/apache/pulsar/client/impl/v5/ProducerBuilderV5.java#L47-L83","documentation":"ProducerBuilderV5.create() blocks on createAsync() and unwraps the CompletionException. Any failure from the async producer-creation pipeline (DAG watch session start, topic layout fetch, segment attach) that is not already a v5 PulsarClientException is rethrown as a plain v5 PulsarClientException wrapping the original cause. It is the library's way of keeping the checked-exception surface uniform across the sync create() path.","triggerScenarios":"Calling producerBuilder.create() when the async pipeline fails with a non-PulsarClientException: e.g. the broker rejects the topic (v4 NotFoundException is mapped specially), a connection drops mid-attach, a timeout in DagWatchClient.start(), or any RuntimeException bubbling out of eagerAttachInitialAsync().","commonSituations":"Topic does not exist and auto-creation is disabled; broker unreachable or TLS handshake failure during segment attach; schema/serialization setup errors; a v4 client that was closed while a producer was being created.","solutions":["Read the wrapped cause via e.getCause() (or print the full stack trace) to see the real failure; fix that root problem.","If the cause is 'topic not found', create the topic or enable auto-creation on the broker.","Verify broker connectivity (serviceUrl, TLS config) before create(); the v5 client connects lazily during producer creation.","For transient network errors, retry create() with backoff; for configuration errors, fix the builder settings instead."],"exampleFix":"// before\nProducer<T> p = client.newProducer(schema).topic(topic).create(); // opaque PulsarClientException\n// after\ntry {\n    Producer<T> p = client.newProducer(schema).topic(topic).create();\n} catch (PulsarClientException e) {\n    LOG.error(\"producer create failed\", e.getCause() != null ? e.getCause() : e);\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"if (topic == null || topic.isEmpty()) throw new IllegalArgumentException(\"topic required before create()\");","typeGuard":null,"tryCatchPattern":"try {\n    Producer<T> p = builder.create();\n} catch (PulsarClientException e) {\n    Throwable root = e.getCause() != null ? e.getCause() : e;\n    if (root instanceof java.util.concurrent.CompletionException ce) root = ce.getCause();\n    LOG.error(\"producer creation failed: {}\", root.toString(), root);\n    throw e;\n}","preventionTips":["Always set topic() before create(); the async path rejects it earlier with InvalidConfigurationException.","Log the full cause chain — create() wraps non-PulsarClientException causes.","Verify broker connectivity with a small health check before creating producers at startup.","Distinguish retryable (network) from permanent (config) causes before retrying."],"tags":["pulsar","producer","async","exception-wrapping"],"backgroundTag":"producer-creation-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"}