{"record":{"id":"8f9d46f4888d0668","repo":"openzipkin/zipkin","slug":"id-is-all-zeros","errorCode":null,"errorMessage":"id is all zeros","messagePattern":"id is all zeros","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"zipkin/src/main/java/zipkin2/Span.java","lineNumber":460,"sourceCode":"\n    /**\n     * Hex encodes the input as the {@link Span#id()} or throws IllegalArgumentException if the\n     * input is zero.\n     */\n    public Builder id(long id) {\n      if (id == 0L) throw new IllegalArgumentException(\"empty id\");\n      this.id = toLowerHex(id);\n      return this;\n    }\n\n    /** Sets {@link Span#id()} or throws {@link IllegalArgumentException} if not lower-hex format. */\n    public Builder id(String id) {\n      if (id == null) throw new NullPointerException(\"id == null\");\n      int length = id.length();\n      if (length == 0) throw new IllegalArgumentException(\"id is empty\");\n      if (length > 16) throw new IllegalArgumentException(\"id.length > 16\");\n      if (validateHexAndReturnZeroPrefix(id) == 16) {\n        throw new IllegalArgumentException(\"id is all zeros\");\n      }\n      this.id = length < 16 ? padLeft(id, 16) : id;\n      return this;\n    }\n\n    /** Sets {@link Span#kind} */\n    public Builder kind(@Nullable Kind kind) {\n      this.kind = kind;\n      return this;\n    }\n\n    /** Sets {@link Span#name} */\n    public Builder name(@Nullable String name) {\n      this.name = name == null || name.isEmpty() ? null : name.toLowerCase(Locale.ROOT);\n      return this;\n    }\n\n    /** Sets {@link Span#timestampAsLong()} */","sourceCodeStart":442,"sourceCodeEnd":478,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin/src/main/java/zipkin2/Span.java#L442-L478","documentation":"Span.Builder.id(String id) throws IllegalArgumentException('id is all zeros') when validateHexAndReturnZeroPrefix(id) returns 16, i.e. the (padded) ID is 16 zero characters. Zipkin forbids a zero span ID because it cannot serve as a unique reference for parent-child links. Note this exact check is length-independent: any all-zero input like \"0\" or \"0000000000000000\" triggers it after padding logic in the helper.","triggerScenarios":"Calling .id(\"0\"), .id(\"0000000000000000\"), or a hex string produced from the long 0L via toLowerHex.","commonSituations":"Converting an absent/failed-to-parse span ID into the literal string of zeros before passing it in; copied test fixtures with zero IDs; upstream services (or W3C traceparent implementations) that emit all-zero IDs to mean 'invalid', forwarded verbatim.","solutions":["Treat an all-zero incoming ID as 'no ID' and generate a fresh one instead of forwarding it.","Fix the conversion step: never stringify a 0L long into an ID — handle 0L at the long level (see error 122).","Sanitize at the edge: reject/replace zero IDs when accepting spans over the wire or from headers."],"exampleFix":"// before\nb.id(toLowerHex(parsedSpanId)); // parsedSpanId == 0 -> \"0000000000000000\"\n\n// after\nb.id(parsedSpanId != 0L ? toLowerHex(parsedSpanId)\n    : toLowerHex(ThreadLocalRandom.current().nextLong()));","handlingStrategy":"validation","validationCode":"boolean allZeros(String s) {\n  return s.chars().allMatch(c -> c == '0');\n}\n// if (sid != null && allZeros(sid)) sid = newSpanIdHex();","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Handle 0L at the long level before stringifying (see 'empty id').","Reject all-zero IDs at ingestion boundaries (collector/reporter)."],"tags":["zipkin","span","span-id","validation","builder"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}