openzipkin/zipkin · error · NullPointerException

sampler == null

Error message

sampler == null

What it means

Collector.Builder.sampler throws NullPointerException when passed null. As with metrics, an unset sampler defaults to CollectorSampler.ALWAYS_SAMPLE in the constructor, but an explicit null is a caller bug and fails fast. Samplers decide what fraction of trace ids are retained by the collector.

Source

Thrown at zipkin-collector/core/src/main/java/zipkin2/collector/Collector.java:73

    }

    /** Sets {@link {@link CollectorComponent.Builder#storage(StorageComponent)}} */
    public Builder storage(StorageComponent storage) {
      if (storage == null) throw new NullPointerException("storage == null");
      this.storage = storage;
      return this;
    }

    /** Sets {@link {@link CollectorComponent.Builder#metrics(CollectorMetrics)}} */
    public Builder metrics(CollectorMetrics metrics) {
      if (metrics == null) throw new NullPointerException("metrics == null");
      this.metrics = metrics;
      return this;
    }

    /** Sets {@link {@link CollectorComponent.Builder#sampler(CollectorSampler)}} */
    public Builder sampler(CollectorSampler sampler) {
      if (sampler == null) throw new NullPointerException("sampler == null");
      this.sampler = sampler;
      return this;
    }

    public Collector build() {
      return new Collector(this);
    }
  }

  final Logger logger;
  final CollectorMetrics metrics;
  final CollectorSampler sampler;
  final StorageComponent storage;

  Collector(Builder builder) {
    if (builder.logger == null) throw new NullPointerException("logger == null");
    this.logger = builder.logger;
    this.metrics = builder.metrics == null ? CollectorMetrics.NOOP_METRICS : builder.metrics;

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Build the sampler with CollectorSampler.create(rate) where rate ∈ [0,1], or omit the call to accept ALWAYS_SAMPLE default.
2. Default explicitly: .sampler(s != null ? s : CollectorSampler.ALWAYS_SAMPLE).
3. Fix the rate parsing so invalid values fail loudly at config load instead of yielding null.

Example fix

// before
Float pct = parsePct(env.get("COLLECTOR_SAMPLE_PERCENTAGE")); // null
builder.sampler(pct == null ? null : CollectorSampler.create(pct)); // NPE when null

// after
builder.sampler(pct == null ? CollectorSampler.ALWAYS_SAMPLE : CollectorSampler.create(pct));

java
CollectorSampler s = (sampler != null) ? sampler : CollectorSampler.ALWAYS_SAMPLE;
builder.sampler(s);

When it happens

Trigger: Calling .sampler(null), commonly when a sampler built from an env string (e.g. COLLECTOR_SAMPLE_PERCENTAGE) is null because parsing code returned null on bad input.

Common situations: Sample-rate property missing/malformed so the factory method returns null; conditional sampler creation on a path that doesn't always run; DI binding absent.

Related errors

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

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