openzipkin/zipkin · error · NullPointerException

category == null

Error message

category == null

What it means

ScribeCollector.Builder.category(String) throws a NullPointerException with message 'category == null' when the category name used to filter Scribe messages is set to null. The category is the Finagle/Scribe log category (default 'zipkin') from which the collector consumes spans. Zipkin fails fast here because a null category cannot be subscribed to and would otherwise fail later at runtime in the Scribe protocol handler.

Source

Thrown at zipkin-collector/scribe/src/main/java/zipkin2/collector/scribe/ScribeCollector.java:52

      delegate.storage(storage);
      return this;
    }

    @Override public Builder metrics(CollectorMetrics metrics) {
      if (metrics == null) throw new NullPointerException("metrics == null");
      this.metrics = metrics.forTransport("scribe");
      delegate.metrics(this.metrics);
      return this;
    }

    @Override public Builder sampler(CollectorSampler sampler) {
      delegate.sampler(sampler);
      return this;
    }

    /** Category zipkin spans will be consumed from. Defaults to "zipkin" */
    public Builder category(String category) {
      if (category == null) throw new NullPointerException("category == null");
      this.category = category;
      return this;
    }

    /** The port to listen on. Defaults to 9410 */
    public Builder port(int port) {
      this.port = port;
      return this;
    }

    @Override public ScribeCollector build() {
      return new ScribeCollector(this);
    }
  }

  final NettyScribeServer server;

  ScribeCollector(Builder builder) {

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Pass a non-null category string, typically the default "zipkin": builder.category("zipkin")
2. If the category comes from config, default it when absent: builder.category(category != null ? category : "zipkin")
3. Check the property name/env var spelling that supplies the category value

Example fix

// before
String cat = System.getenv("SCRIBE_CATEGORY"); // null if unset
ScribeCollector collector = ScribeCollector.newBuilder().category(cat).port(9410).build();

// after
String cat = System.getenv("SCRIBE_CATEGORY");
if (cat == null) cat = "zipkin";
ScribeCollector collector = ScribeCollector.newBuilder().category(cat).port(9410).build();

String category = System.getenv("SCRIBE_CATEGORY");
if (category == null) category = "zipkin";
// now safe: ScribeCollector.newBuilder().category(category)

When it happens

Trigger: Calling ScribeCollector.newBuilder().category(null), or passing a variable that was never initialized (e.g. a config property that resolved to null via System.getenv or a properties file) into .category(...).

Common situations: Wiring the Scribe collector from environment variables or Spring property placeholders where the category key is misspelled or absent; refactoring code that previously hardcoded 'zipkin'.

Related errors

• metrics == null
• storage == null
• metrics == null
• sampler == null
• rate should be between 0 and 1: was {}

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