openzipkin/zipkin · error · Error

v1 format is not supported. For help, contact https://gitter

Error message

v1 format is not supported. For help, contact https://gitter.im/openzipkin/zipkin

What it means

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.

Source

Thrown at zipkin-lens/src/util/trace.js:17

/*
 * Copyright The OpenZipkin Authors
 * SPDX-License-Identifier: Apache-2.0
 */
export const ensureV2TraceData = (trace) => {
  if (!Array.isArray(trace) || trace.length === 0) {
    throw new Error('input is not a list');
  }
  const [first] = trace;
  if (!first.traceId || !first.id) {
    throw new Error('List<Span> implies at least traceId and id fields');
  }
  if (
    first.binaryAnnotations ||
    (!first.localEndpoint && !first.remoteEndpoint && !first.tags)
  ) {
    throw new Error(
      'v1 format is not supported. For help, contact https://gitter.im/openzipkin/zipkin',
    );
  }
};

export const hasRootSpan = (trace) => {
  switch (trace.length) {
    case 0:
      return false;
    case 1:
      return true;
    default:
      if (trace[0].depth < trace[1].depth) {
        return true;
      }
      return false;
  }
};

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Serve/convert data to v2 format: map v1 annotations to v2 kind/timestamp fields and binaryAnnotations to tags, and attach localEndpoint/remoteEndpoint objects.
2. If using old Zipkin 1.x, upgrade the server or use its v2 API endpoints so responses are already List<v2 Span>.
3. For minimal spans with no endpoints or tags, add at least a localEndpoint (e.g. {serviceName:'unknown'}) so the v2 heuristic passes.

Example fix

// before
const v1Span = { traceId: 'a', id: 'b', binaryAnnotations: [{ key: 'lc', value: 'x' }] };
ensureV2TraceData([v1Span]); // throws 'v1 format is not supported'

// after
const v2Span = {
  traceId: 'a', id: 'b', name: 'op',
  localEndpoint: { serviceName: 'svc' },
  tags: { lc: 'x' },
};
ensureV2TraceData([v2Span]);

const looksV1 = (s) => !!s.binaryAnnotations || (!s.localEndpoint && !s.remoteEndpoint && !s.tags);
if (spans.some(looksV1)) throw new Error('convert v1 spans to v2 before rendering');

const isV2SpanShape = (s) => !s.binaryAnnotations && (s.localEndpoint || s.remoteEndpoint || typeof s.tags === 'object');

try {
  ensureV2TraceData(trace);
} catch (e) {
  if (e.message.includes('v1 format')) convertV1toV2(trace); // or show upgrade notice
  else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• input is not a list
• List<Span> implies at least traceId and id fields
• Trace ${traceId} is missing a timestamp
• Trace ${modelview.traceId} is missing a timestamp
• concurrency < 1

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