{"record":{"id":"6ea4664f8fa32c33","repo":"apache/pulsar","slug":"error-creating-client-for-healthchecker","errorCode":null,"errorMessage":"Error creating client for HealthChecker","messagePattern":"Error creating client for HealthChecker","errorType":"exception","errorClass":"PulsarServerException","httpStatus":null,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/service/HealthChecker.java","lineNumber":127,"sourceCode":"\n    private final Duration timeout = DEFAULT_HEALTH_CHECK_READ_TIMEOUT;\n\n    public HealthChecker(PulsarService pulsar) throws PulsarServerException {\n        this.pulsar = pulsar;\n        this.heartbeatTopic = getHeartbeatTopicName(pulsar.getBrokerId(), pulsar.getConfiguration());\n        this.lookupExecutor =\n                new ScheduledExecutorProvider(1, \"health-checker-client-lookup-executor\");\n        this.scheduledExecutorProvider =\n                new ScheduledExecutorProvider(1, \"health-checker-client-scheduled-executor\");\n        this.healthCheckExecutor =\n                Executors.newSingleThreadScheduledExecutor(new DefaultThreadFactory(\"health-checker-executor\"));\n        try {\n            this.client = pulsar.createClientImpl(builder -> {\n                builder.lookupExecutorProvider(lookupExecutor);\n                builder.scheduledExecutorProvider(scheduledExecutorProvider);\n            });\n        } catch (PulsarClientException e) {\n            throw new PulsarServerException(\"Error creating client for HealthChecker\", e);\n        }\n    }\n\n    private static String getHeartbeatTopicName(String brokerId, ServiceConfiguration configuration) {\n        NamespaceName namespaceName = NamespaceService.getHeartbeatNamespace(brokerId, configuration);\n        return String.format(\"persistent://%s/%s\", namespaceName, HEALTH_CHECK_TOPIC_SUFFIX);\n    }\n\n    /**\n     * Performs a health check on the broker by verifying message production and consumption.\n     * The health check process includes:\n     * 1. Producing a test message\n     * 2. Reading the message back to verify end-to-end functionality\n     *\n     * @param clientAppId  The identifier of the client application requesting the health check\n     * @return A CompletableFuture that completes when the health check is successful, or completes exceptionally if the\n     * check fails\n     */","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/service/HealthChecker.java#L109-L145","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the chained PulsarClientException cause for the root reason","Verify broker client settings: serviceUrl, authPlugin/authParams, TLS config are valid","Ensure advertisedAddress/listener configuration resolves correctly","Check for resource limits (file descriptors, threads) preventing netty/executor setup"],"exampleFix":"// broker.conf — fix invalid service url\n// before\nadvertisedAddress=localhost.invalid\n// after\nadvertisedAddress=broker-1.cluster.example.com","handlingStrategy":"try-catch","validationCode":"// pre-flight: validate client config constructs a client\nPulsarClient preflight = PulsarClient.builder().serviceUrl(serviceUrl)\n    .authentication(authPlugin, authParams).build();\npreflight.close();","typeGuard":null,"tryCatchPattern":"try {\n    startHealthChecker();\n} catch (PulsarServerException e) {\n    log.error(\"HealthChecker client init failed: {}\", e.getCause().getMessage());\n}","preventionTips":["Validate broker serviceUrl/advertisedAddress/TLS settings before startup","Keep auth plugin classnames and authParams correct in broker.conf","Watch fd/thread limits on brokers hosting health checks"],"tags":["java","broker","health-check","pulsar-client","startup"],"backgroundTag":"client-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"}