{"record":{"id":"5fa14f5fa1649b22","repo":"openzipkin/zipkin","slug":"v1-format-is-not-supported-for-help-contact-http","errorCode":null,"errorMessage":"v1 format is not supported. For help, contact https://gitter.im/openzipkin/zipkin","messagePattern":"v1 format is not supported\\. For help, contact https://gitter\\.im/openzipkin/zipkin","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"zipkin-lens/src/util/trace.js","lineNumber":17,"sourceCode":"/*\n * Copyright The OpenZipkin Authors\n * SPDX-License-Identifier: Apache-2.0\n */\nexport const ensureV2TraceData = (trace) => {\n  if (!Array.isArray(trace) || trace.length === 0) {\n    throw new Error('input is not a list');\n  }\n  const [first] = trace;\n  if (!first.traceId || !first.id) {\n    throw new Error('List<Span> implies at least traceId and id fields');\n  }\n  if (\n    first.binaryAnnotations ||\n    (!first.localEndpoint && !first.remoteEndpoint && !first.tags)\n  ) {\n    throw new Error(\n      'v1 format is not supported. For help, contact https://gitter.im/openzipkin/zipkin',\n    );\n  }\n};\n\nexport const hasRootSpan = (trace) => {\n  switch (trace.length) {\n    case 0:\n      return false;\n    case 1:\n      return true;\n    default:\n      if (trace[0].depth < trace[1].depth) {\n        return true;\n      }\n      return false;\n  }\n};","sourceCodeStart":1,"sourceCodeEnd":35,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-lens/src/util/trace.js#L1-L35","documentation":"Thrown by zipkin-lens's ensureV2TraceData when the first span looks like v1 format: it has binaryAnnotations, or it has none of the v2 fields localEndpoint, remoteEndpoint, or tags. Zipkin Lens only renders v2 (JSON v2 / Span model) data; v1 spans with binaryAnnotations/annotations must be converted server-side first. The message points users at the OpenZipkin community chat.","triggerScenarios":"Calling ensureV2TraceData with v1 spans such as {traceId, id, binaryAnnotations:[...]} or {traceId, id, annotations:[...]} with no localEndpoint/remoteEndpoint/tags; or with a bare span {traceId, id} only — which also matches the 'no v2 fields' branch.","commonSituations":"Pointing the lens UI or trace rendering at an old Zipkin 1.x server or a trace file exported in v1 format; a new minimal span that carries only ids and a name (the heuristic misclassifies it); mixed v1/v2 data in the same pipeline.","solutions":["Serve/convert data to v2 format: map v1 annotations to v2 kind/timestamp fields and binaryAnnotations to tags, and attach localEndpoint/remoteEndpoint objects.","If using old Zipkin 1.x, upgrade the server or use its v2 API endpoints so responses are already List<v2 Span>.","For minimal spans with no endpoints or tags, add at least a localEndpoint (e.g. {serviceName:'unknown'}) so the v2 heuristic passes."],"exampleFix":"// before\nconst v1Span = { traceId: 'a', id: 'b', binaryAnnotations: [{ key: 'lc', value: 'x' }] };\nensureV2TraceData([v1Span]); // throws 'v1 format is not supported'\n\n// after\nconst v2Span = {\n  traceId: 'a', id: 'b', name: 'op',\n  localEndpoint: { serviceName: 'svc' },\n  tags: { lc: 'x' },\n};\nensureV2TraceData([v2Span]);","handlingStrategy":"validation","validationCode":"const looksV1 = (s) => !!s.binaryAnnotations || (!s.localEndpoint && !s.remoteEndpoint && !s.tags);\nif (spans.some(looksV1)) throw new Error('convert v1 spans to v2 before rendering');","typeGuard":"const isV2SpanShape = (s) => !s.binaryAnnotations && (s.localEndpoint || s.remoteEndpoint || typeof s.tags === 'object');","tryCatchPattern":"try {\n  ensureV2TraceData(trace);\n} catch (e) {\n  if (e.message.includes('v1 format')) convertV1toV2(trace); // or show upgrade notice\n  else throw e;\n}","preventionTips":["Always fetch traces from v2 API endpoints (/traces, not v1 endpoints).","Give minimal spans at least a localEndpoint so the v2 heuristic passes."],"tags":["zipkin","javascript","validation","data-format","v1-migration"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}