{"record":{"id":"eac39947261ec723","repo":"openzipkin/zipkin","slug":"pulsar-client-creation-failed","errorCode":null,"errorMessage":"Pulsar client creation failed. {}","messagePattern":"Pulsar client creation failed\\. (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"zipkin-collector/pulsar/src/main/java/zipkin2/collector/pulsar/LazyPulsarInit.java","lineNumber":53,"sourceCode":"  void init() {\n    if (result == null) {\n      synchronized (this) {\n        if (result == null) {\n          result = subscribe();\n        }\n      }\n    }\n  }\n\n  private PulsarClient subscribe() {\n    PulsarClient client;\n    try {\n      client = PulsarClient.builder()\n          .loadConf(clientProps)\n          .build();\n    } catch (Exception e) {\n      failure.set(CheckResult.failed(e));\n      throw new RuntimeException(\"Pulsar client creation failed. \" + e.getMessage(), e);\n    }\n\n    try {\n      for (int i = 0; i < concurrency; i++) {\n        PulsarSpanConsumer consumer = new PulsarSpanConsumer(topic, consumerProps, client, collector, metrics);\n        consumer.startConsumer();\n      }\n      return client;\n    } catch (Exception e) {\n      try {\n        client.close();\n      } catch (PulsarClientException ex) {\n        // Nobody cares me.\n      }\n      failure.set(CheckResult.failed(e));\n      throw new RuntimeException(\"Pulsar Client is unable to subscribe to the topic(\" + topic + \"), please check the service.\", e);\n    }\n  }","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-collector/pulsar/src/main/java/zipkin2/collector/pulsar/LazyPulsarInit.java#L35-L71","documentation":"LazyPulsarInit.subscribe() wraps any exception thrown while building the PulsarClient in a RuntimeException ('Pulsar client creation failed. ...'). PulsarClient.builder().loadConf(clientProps).build() fails on an invalid/unreachable serviceUrl, missing required config, bad auth settings, or incompatible client/broker versions. The CheckResult is also recorded as failed so the collector's check() reports unhealthy.","triggerScenarios":"PulsarCollector built with a malformed serviceUrl (not pulsar://host:port or http://...), a broker that is unreachable at connect time, invalid TLS/auth configuration in clientProps, or a Pulsar client version mismatch. The error surfaces lazily on first use (check()/accept of the first span), not at build().","commonSituations":"Service URL typo (e.g. missing pulsar:// scheme), broker DNS not resolvable in Kubernetes, TLS enabled broker with plaintext client config, or auth plugin not on the classpath.","solutions":["Verify the serviceUrl format, e.g. pulsar://my-broker:6650, and that the broker host:port is reachable (telnet/grpcurl)","Check the wrapped cause (e) in the stack trace — it names the real PulsarClientException reason","Validate TLS/authentication settings in clientProps against the broker configuration","Check client/broker version compatibility if the cause indicates an unsupported protocol"],"exampleFix":"// before\nPulsarCollector.newBuilder(ctx)\n  .serviceUrl(\"my-broker:6650\") // missing scheme\n  ...\n\n// after\nPulsarCollector.newBuilder(ctx)\n  .serviceUrl(\"pulsar://my-broker:6650\")\n  ...","handlingStrategy":"try-catch","validationCode":"// Validate the URL shape before building the collector\nURI uri = URI.create(serviceUrl);\nif (!(\"pulsar\".equals(uri.getScheme()) || \"http\".equals(uri.getScheme()) || \"https\".equals(uri.getScheme()))) {\n  throw new IllegalArgumentException(\"serviceUrl must start with pulsar:// or http(s)://\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  collector.check(); // triggers lazy init\n} catch (RuntimeException e) {\n  Throwable cause = e.getCause();\n  log.error(\"Pulsar client init failed: {}\", cause.getMessage(), e);\n  // surface as unhealthy and let orchestration restart/backoff\n}","preventionTips":["Pre-flight the serviceUrl scheme and network reachability before wiring the collector","Log and inspect the wrapped cause — the real PulsarClientException explains the failure","Run the collector behind a health check so a failed lazy init shows up as unhealthy rather than silent"],"tags":["pulsar","zipkin","connection","configuration","runtime-exception"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}