openzipkin/zipkin · critical · RuntimeException

Pulsar Client is unable to subscribe to the topic({}), pleas

Error message

Pulsar Client is unable to subscribe to the topic({}), please check the service.

What it means

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.

Source

Thrown at zipkin-collector/pulsar/src/main/java/zipkin2/collector/pulsar/LazyPulsarInit.java:69

    } catch (Exception e) {
      failure.set(CheckResult.failed(e));
      throw new RuntimeException("Pulsar client creation failed. " + e.getMessage(), e);
    }

    try {
      for (int i = 0; i < concurrency; i++) {
        PulsarSpanConsumer consumer = new PulsarSpanConsumer(topic, consumerProps, client, collector, metrics);
        consumer.startConsumer();
      }
      return client;
    } catch (Exception e) {
      try {
        client.close();
      } catch (PulsarClientException ex) {
        // Nobody cares me.
      }
      failure.set(CheckResult.failed(e));
      throw new RuntimeException("Pulsar Client is unable to subscribe to the topic(" + topic + "), please check the service.", e);
    }
  }

  void close() throws PulsarClientException {
    PulsarClient maybe = result;
    if (maybe != null) {
      result.close();
      result = null;
    }
  }
}

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Create the topic or enable auto-creation: pulsar-admin topics create persistent://tenant/namespace/zipkin
2. Inspect the wrapped cause for the exact PulsarClientException (NotFound / NotAuthorized / InvalidSubscriptionName)
3. Grant the client role consume permission on the topic's namespace
4. Use a unique subscriptionName per collector deployment if the subscription type is Exclusive

Example fix

// before
// topic 'zipkin' never created, auto-create disabled on broker

// after
// bin/pulsar-admin topics create persistent://public/default/zipkin
PulsarCollector.newBuilder(ctx).topic("zipkin").subscriptionName("zipkin-collector").serviceUrl("pulsar://my-broker:6650")...

// Ensure topic + subscription are set and non-empty before build
requireNonEmpty(topic, "topic");
requireNonEmpty(subscriptionName, "subscriptionName");

try {
  collector.check();
} catch (RuntimeException e) {
  log.error("Pulsar subscribe failed for topic {}: {}", topic, e.getCause().getMessage(), e);
  // verify topic exists / permissions, then restart with backoff
}

When it happens

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

Common situations: 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.

Related errors

• topic is null or empty
• Pulsar client creation failed. {}
• metrics == null
• concurrency < 1
• serviceUrl is null or empty

AI-assisted analysis of openzipkin/zipkin@878ce2a1fa (2026-08-14). Data as JSON: /api/errors/50325afed96983dd. Report an issue: GitHub.