openzipkin/zipkin · error · NullPointerException

traceId == null

Error message

traceId == null

What it means

Span.normalizeTraceId(String) throws NullPointerException('traceId == null') when the argument is null. This static helper validates and pads a hex trace ID to 16 or 32 chars, and it is also called from Span.Builder.traceId(String). Null is rejected up front because there is no normalized representation of 'no trace ID'.

Source

Thrown at zipkin/src/main/java/zipkin2/Span.java:623

      }
      return new Span(this);
    }

    Builder() {
    }
  }

  @Override public String toString() {
    return new String(SpanBytesEncoder.JSON_V2.encode(this), UTF_8);
  }

  /**
   * Returns a valid lower-hex trace ID, padded left as needed to 16 or 32 characters.
   *
   * @throws IllegalArgumentException if oversized or not lower-hex
   */
  public static String normalizeTraceId(String traceId) {
    if (traceId == null) throw new NullPointerException("traceId == null");
    int length = traceId.length();
    if (length == 0) throw new IllegalArgumentException("traceId is empty");
    if (length > 32) throw new IllegalArgumentException("traceId.length > 32");
    int zeros = validateHexAndReturnZeroPrefix(traceId);
    if (zeros == length) throw new IllegalArgumentException("traceId is all zeros");
    if (length == 32 || length == 16) {
      if (length == 32 && zeros >= 16) return traceId.substring(16);
      return traceId;
    } else if (length < 16) {
      return padLeft(traceId, 16);
    } else {
      return padLeft(traceId, 32);
    }
  }

  static final String THIRTY_TWO_ZEROS;
  static {
    char[] zeros = new char[32];

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Null-check before normalizing: treat null as 'no trace ID' and handle at the call site.
2. Fix the source of the null (missing header/context) rather than normalizing downstream.
3. If null is legitimate in your flow, wrap: id == null ? null : Span.normalizeTraceId(id).

Example fix

// before
String traceId = Span.normalizeTraceId(mdc.get("traceId"));

// after
String raw = mdc.get("traceId");
String traceId = raw == null ? null : Span.normalizeTraceId(raw);

String safe = raw == null ? null : Span.normalizeTraceId(raw);

When it happens

Trigger: Calling Span.normalizeTraceId(null) directly, or Span.Builder.traceId((String) null) — e.g. passing a value looked up from headers/MDC that was absent.

Common situations: Utility code that normalizes IDs read from B3 headers, MDC, or log correlation fields where the field may be missing; bridging code between Brave/other tracers and raw zipkin2 Span objects.

Related errors

• empty trace ID
• traceId is empty
• traceId is all zeros
• should be lower-hex encoded with no prefix
• traceId == 0

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