apache/pulsar · error · PulsarClientException

(wraps v4 producer error message)

Error message

(wraps v4 producer error message)

What it means

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.

Source

Thrown at pulsar-client-v5/src/main/java/org/apache/pulsar/client/impl/v5/ScalableTopicProducer.java:639

        }
    }

    /**
     * Sync wrapper around {@link #getOrCreateSegmentProducerAsync}. Only safe to
     * call from user threads (never from a netty IO thread) since it blocks until
     * the segment producer is ready.
     */
    private org.apache.pulsar.client.api.Producer<T> getOrCreateSegmentProducer(long segmentId)
            throws PulsarClientException {
        try {
            return getOrCreateSegmentProducerAsync(segmentId).get();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new PulsarClientException("Interrupted while creating segment producer", e);
        } catch (ExecutionException e) {
            Throwable cause = e.getCause();
            if (cause instanceof org.apache.pulsar.client.api.PulsarClientException v4Exc) {
                throw new PulsarClientException(v4Exc.getMessage(), v4Exc);
            }
            if (cause instanceof PulsarClientException v5Exc) {
                throw v5Exc;
            }
            throw new PulsarClientException(cause != null ? cause : e);
        }
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Read the chained cause's message to identify the v4 failure (NotFound/NotAllowed/ConnectError).
2. If topic-not-found after a split, ensure the broker has created the new segment topic or wait for layout watch before retrying.
3. Fix client permissions (grant produce on segment topic pattern) if authorization failed.
4. Verify broker availability and serviceUrl if the cause is a connection error.

Example fix

// before
// v4 ProducerException 'Topic not found' surfaces as opaque failure
// after
admin.topics().createSegmentTopic(segmentId); // or grant produce permission, then retry send

// preflight: verify produce permission and topic existence
admin.topics().getSubscriptions(segmentTopic); // throws if topic missing
// check auth: ensure client role has produce on the segment topic pattern

try {
    producer.send(msg);
} catch (PulsarClientException e) {
    log.error("segment producer failed", e.getCause());
    // cause message tells: NotFound -> wait for topic creation; NotAllowed -> fix permissions
}

When it happens

Trigger: 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.

Common situations: Segment topic not yet created after a split; missing permissions on auto-created partition/segment topics; broker down or unreachable; topic name misconfiguration.

Related errors

• Error creating client for HealthChecker
• (wraps underlying failure cause)
• (wraps v4 producer send failure message)
• Interrupted while creating segment producer
• (wraps subscribeAsync failure cause)

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/0e62de1f787bf474. Report an issue: GitHub.