{"record":{"id":"0e62de1f787bf474","repo":"apache/pulsar","slug":"wraps-v4-producer-error-message","errorCode":null,"errorMessage":"(wraps v4 producer error message)","messagePattern":"\\(wraps v4 producer error message\\)","errorType":"exception","errorClass":"PulsarClientException","httpStatus":null,"severity":"error","filePath":"pulsar-client-v5/src/main/java/org/apache/pulsar/client/impl/v5/ScalableTopicProducer.java","lineNumber":639,"sourceCode":"        }\n    }\n\n    /**\n     * Sync wrapper around {@link #getOrCreateSegmentProducerAsync}. Only safe to\n     * call from user threads (never from a netty IO thread) since it blocks until\n     * the segment producer is ready.\n     */\n    private org.apache.pulsar.client.api.Producer<T> getOrCreateSegmentProducer(long segmentId)\n            throws PulsarClientException {\n        try {\n            return getOrCreateSegmentProducerAsync(segmentId).get();\n        } catch (InterruptedException e) {\n            Thread.currentThread().interrupt();\n            throw new PulsarClientException(\"Interrupted while creating segment producer\", e);\n        } catch (ExecutionException e) {\n            Throwable cause = e.getCause();\n            if (cause instanceof org.apache.pulsar.client.api.PulsarClientException v4Exc) {\n                throw new PulsarClientException(v4Exc.getMessage(), v4Exc);\n            }\n            if (cause instanceof PulsarClientException v5Exc) {\n                throw v5Exc;\n            }\n            throw new PulsarClientException(cause != null ? cause : e);\n        }\n    }\n}\n","sourceCodeStart":621,"sourceCodeEnd":648,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client-v5/src/main/java/org/apache/pulsar/client/impl/v5/ScalableTopicProducer.java#L621-L648","documentation":"If the async segment-producer creation fails with an org.apache.pulsar.client.api.PulsarClientException (the v4 client type), it is rethrown as the v5 PulsarClientException carrying the v4 message and chained cause. The message is the underlying v4 producer error text.","triggerScenarios":"getOrCreateSegmentProducer during send, onLayoutChange, or eager attach where the v4 client fails to create the per-segment producer: topic does not exist, authorization failure, namespace policy rejection, or broker connect error.","commonSituations":"Segment topic not yet created after a split; missing permissions on auto-created partition/segment topics; broker down or unreachable; topic name misconfiguration.","solutions":["Read the chained cause's message to identify the v4 failure (NotFound/NotAllowed/ConnectError).","If topic-not-found after a split, ensure the broker has created the new segment topic or wait for layout watch before retrying.","Fix client permissions (grant produce on segment topic pattern) if authorization failed.","Verify broker availability and serviceUrl if the cause is a connection error."],"exampleFix":"// before\n// v4 ProducerException 'Topic not found' surfaces as opaque failure\n// after\nadmin.topics().createSegmentTopic(segmentId); // or grant produce permission, then retry send","handlingStrategy":"try-catch","validationCode":"// preflight: verify produce permission and topic existence\nadmin.topics().getSubscriptions(segmentTopic); // throws if topic missing\n// check auth: ensure client role has produce on the segment topic pattern","typeGuard":null,"tryCatchPattern":"try {\n    producer.send(msg);\n} catch (PulsarClientException e) {\n    log.error(\"segment producer failed\", e.getCause());\n    // cause message tells: NotFound -> wait for topic creation; NotAllowed -> fix permissions\n}","preventionTips":["Grant produce permission on the segment topic pattern up front","Wait for the broker to create new segment topics after a split before sending","Verify broker availability and serviceUrl in preflight health checks"],"tags":["segment-producer","wrapped-exception","broker","pulsar-client"],"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-14T05:17:10.506Z"}