apache/pulsar · error · PulsarServerException

Error creating client for HealthChecker

Error message

Error creating client for HealthChecker

What it means

HealthChecker creates an internal Pulsar client to probe broker health via heartbeat topics. If PulsarClient creation fails (PulsarClientException), it is wrapped in PulsarServerException 'Error creating client for HealthChecker'.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/service/HealthChecker.java:127

    private final Duration timeout = DEFAULT_HEALTH_CHECK_READ_TIMEOUT;

    public HealthChecker(PulsarService pulsar) throws PulsarServerException {
        this.pulsar = pulsar;
        this.heartbeatTopic = getHeartbeatTopicName(pulsar.getBrokerId(), pulsar.getConfiguration());
        this.lookupExecutor =
                new ScheduledExecutorProvider(1, "health-checker-client-lookup-executor");
        this.scheduledExecutorProvider =
                new ScheduledExecutorProvider(1, "health-checker-client-scheduled-executor");
        this.healthCheckExecutor =
                Executors.newSingleThreadScheduledExecutor(new DefaultThreadFactory("health-checker-executor"));
        try {
            this.client = pulsar.createClientImpl(builder -> {
                builder.lookupExecutorProvider(lookupExecutor);
                builder.scheduledExecutorProvider(scheduledExecutorProvider);
            });
        } catch (PulsarClientException e) {
            throw new PulsarServerException("Error creating client for HealthChecker", e);
        }
    }

    private static String getHeartbeatTopicName(String brokerId, ServiceConfiguration configuration) {
        NamespaceName namespaceName = NamespaceService.getHeartbeatNamespace(brokerId, configuration);
        return String.format("persistent://%s/%s", namespaceName, HEALTH_CHECK_TOPIC_SUFFIX);
    }

    /**
     * Performs a health check on the broker by verifying message production and consumption.
     * The health check process includes:
     * 1. Producing a test message
     * 2. Reading the message back to verify end-to-end functionality
     *
     * @param clientAppId  The identifier of the client application requesting the health check
     * @return A CompletableFuture that completes when the health check is successful, or completes exceptionally if the
     * check fails
     */

View on GitHub (pinned to 820761864e)

Solutions

  1. Inspect the chained PulsarClientException cause for the root reason
  2. Verify broker client settings: serviceUrl, authPlugin/authParams, TLS config are valid
  3. Ensure advertisedAddress/listener configuration resolves correctly
  4. Check for resource limits (file descriptors, threads) preventing netty/executor setup

Example fix

// broker.conf — fix invalid service url
// before
advertisedAddress=localhost.invalid
// after
advertisedAddress=broker-1.cluster.example.com
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight: validate client config constructs a client
PulsarClient preflight = PulsarClient.builder().serviceUrl(serviceUrl)
    .authentication(authPlugin, authParams).build();
preflight.close();

Try / catch

try {
    startHealthChecker();
} catch (PulsarServerException e) {
    log.error("HealthChecker client init failed: {}", e.getCause().getMessage());
}

Prevention

When it happens

Trigger: Broker startup or health-check initialization when pulsar.createClientImpl(...) throws — e.g. invalid service URL, missing authentication configuration, unreachable configuration store, or bad client builder settings.

Common situations: Misconfigured brokerServiceUrl/advertisedAddress; auth plugins configured incorrectly so the internal client can't be constructed; resource exhaustion (threads/memory) creating client IO threads; invalid TLS settings.

Related errors

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