{"record":{"id":"8093850639ba0ae7","repo":"openzipkin/zipkin","slug":"traceid-0","errorCode":null,"errorMessage":"traceId == 0","messagePattern":"traceId == 0","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"zipkin/src/main/java/zipkin2/v1/V1Span.java","lineNumber":93,"sourceCode":"   */\n  public List<V1BinaryAnnotation> binaryAnnotations() {\n    return binaryAnnotations;\n  }\n\n  /** Same as {@link Span#debug()} */\n  public Boolean debug() {\n    return debug;\n  }\n\n  final long traceIdHigh, traceId, id;\n  final String name;\n  final long parentId, timestamp, duration;\n  final List<V1Annotation> annotations;\n  final List<V1BinaryAnnotation> binaryAnnotations;\n  final Boolean debug;\n\n  V1Span(Builder builder) {\n    if (builder.traceId == 0L) throw new IllegalArgumentException(\"traceId == 0\");\n    if (builder.id == 0L) throw new IllegalArgumentException(\"id == 0\");\n    this.traceId = builder.traceId;\n    this.traceIdHigh = builder.traceIdHigh;\n    this.name = builder.name;\n    this.id = builder.id;\n    this.parentId = builder.parentId;\n    this.timestamp = builder.timestamp;\n    this.duration = builder.duration;\n    this.annotations = sortedList(builder.annotations);\n    this.binaryAnnotations = sortedList(builder.binaryAnnotations);\n    this.debug = builder.debug;\n  }\n\n  public static Builder newBuilder() {\n    return new Builder();\n  }\n\n  public static final class Builder {","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin/src/main/java/zipkin2/v1/V1Span.java#L75-L111","documentation":"Thrown by the V1Span constructor (zipkin2.v1) when the builder's 64-bit traceId is 0. A span's traceId identifies the trace it belongs to; 0 is reserved to mean 'unset' in Zipkin, so constructing a V1 span without a real trace id is treated as a programming error.","triggerScenarios":"Building a V1Span with new V1Span.Builder(0L, id); parsing v1 JSON where the 128-bit trace id string is malformed so the low 64 bits parse as 0; converting instrumentation data whose traceId field was never populated or was truncated to 0 by a hex-parsing bug.","commonSituations":"Custom instrumentation or a bridging layer (e.g. translating from another tracing system) that leaves traceId unset; lower-case/upper-case hex parsing that fails silently and returns 0; tests that build V1 spans with placeholder zero ids.","solutions":["Always supply a non-zero 64-bit trace id when constructing the V1Span builder","If the id arrives as hex, validate parse output: reject empty strings and check the parsed long is != 0 before building","Generate ids with a proper id generator (e.g. zipkin's or Brave's) instead of constants like 0L in tests"],"exampleFix":"// before\nV1Span span = new V1Span.Builder(0L, 1L).name(\"get\").build();\n\n// after\nV1Span span = new V1Span.Builder(0LL + traceIdFromContext, 1L).name(\"get\").build();","handlingStrategy":"validation","validationCode":"// validate before constructing the V1 span\nif (traceId == 0L) {\n    throw new IllegalArgumentException(\n        \"traceId is required: got 0 (unset or failed hex parse) for id=\" + id);\n}\nV1Span span = new V1Span.Builder(traceId, id).name(name).build();","typeGuard":null,"tryCatchPattern":"try {\n    return new V1Span.Builder(traceId, id).name(name).build();\n} catch (IllegalArgumentException e) {\n    // drop or reject the malformed span record; never retry with the same ids\n    LOG.warn(\"Discarding span with invalid ids: traceId={}, id={}\", traceId, id);\n    return null; // or route to a dead-letter path\n}","preventionTips":["Validate upstream trace id strings: non-empty, hex-only, and parsed value != 0","Use zipkin/Brave id generators for tests instead of 0L placeholders","Fail instrumentation wiring at startup if no trace context is attached"],"tags":["java","zipkin","validation","trace-id","v1-api"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}