{"record":{"id":"50325afed96983dd","repo":"openzipkin/zipkin","slug":"pulsar-client-is-unable-to-subscribe-to-the-topic","errorCode":null,"errorMessage":"Pulsar Client is unable to subscribe to the topic({}), please check the service.","messagePattern":"Pulsar Client is unable to subscribe to the topic\\((.+?)\\), please check the service\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"zipkin-collector/pulsar/src/main/java/zipkin2/collector/pulsar/LazyPulsarInit.java","lineNumber":69,"sourceCode":"    } 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  }\n\n  void close() throws PulsarClientException {\n    PulsarClient maybe = result;\n    if (maybe != null) {\n      result.close();\n      result = null;\n    }\n  }\n}","sourceCodeStart":51,"sourceCodeEnd":80,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-collector/pulsar/src/main/java/zipkin2/collector/pulsar/LazyPulsarInit.java#L51-L80","documentation":"LazyPulsarInit.subscribe() throws this RuntimeException when creating or starting the PulsarSpanConsumer instances fails (one per concurrency). This happens when the client cannot subscribe to the topic — nonexistent/non-permitted topic, invalid subscription name, authorization failure, or broker-side errors. The client is closed, the CheckResult is set to failed, and the original exception is attached as the cause.","triggerScenarios":"Topic named by .topic(...) does not exist and auto-creation is disabled on the broker; subscriptionName is invalid; the client lacks consume permissions on the namespace; or the broker rejects the subscription (e.g. it is already taken with incompatible config). Raised lazily on first collector use.","commonSituations":"Fresh Pulsar deployment without the 'zipkin' topic created, tenant/namespace authorization not granted to the collector's role, or a subscription name colliding with an existing exclusive subscription.","solutions":["Create the topic or enable auto-creation: pulsar-admin topics create persistent://tenant/namespace/zipkin","Inspect the wrapped cause for the exact PulsarClientException (NotFound / NotAuthorized / InvalidSubscriptionName)","Grant the client role consume permission on the topic's namespace","Use a unique subscriptionName per collector deployment if the subscription type is Exclusive"],"exampleFix":"// before\n// topic 'zipkin' never created, auto-create disabled on broker\n\n// after\n// bin/pulsar-admin topics create persistent://public/default/zipkin\nPulsarCollector.newBuilder(ctx).topic(\"zipkin\").subscriptionName(\"zipkin-collector\").serviceUrl(\"pulsar://my-broker:6650\")...","handlingStrategy":"try-catch","validationCode":"// Ensure topic + subscription are set and non-empty before build\nrequireNonEmpty(topic, \"topic\");\nrequireNonEmpty(subscriptionName, \"subscriptionName\");","typeGuard":null,"tryCatchPattern":"try {\n  collector.check();\n} catch (RuntimeException e) {\n  log.error(\"Pulsar subscribe failed for topic {}: {}\", topic, e.getCause().getMessage(), e);\n  // verify topic exists / permissions, then restart with backoff\n}","preventionTips":["Pre-create the zipkin topic in provisioning scripts instead of relying on broker auto-creation","Grant consume permissions to the collector role before first deploy","Use per-deployment subscription names to avoid exclusive-subscription collisions"],"tags":["pulsar","zipkin","subscription","topic","permissions"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}