openzipkin/zipkin · error · Error

List<Span> implies at least traceId and id fields

Error message

List<Span> implies at least traceId and id fields

What it means

Thrown by zipkin-lens's ensureV2TraceData when the input is a non-empty array but its first element lacks a truthy traceId or id. Every Zipkin span (v2 format) must carry at least traceId and id; this check catches arrays whose elements are not span objects before the UI tries to build a span tree.

Source

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

/*
 * 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:

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Ensure every element of the array is a v2 span with non-empty traceId and id hex strings.
2. Filter out non-span entries before validation: arr.filter(s => s && s.traceId && s.id).
3. Regenerate the fixture/data from a real Zipkin server response so span shape is correct.

Example fix

// before
ensureV2TraceData([{ name: 'get', duration: 10 }]); // throws

// after
const spans = raw.filter((s) => s && s.traceId && s.id);
ensureV2TraceData(spans);

const hasRequiredIds = (arr) => arr.every((s) => s && s.traceId && s.id);
if (!hasRequiredIds(spans)) throw new TypeError('every span needs traceId and id');

const isV2Span = (s) => typeof s === 'object' && s !== null && typeof s.traceId === 'string' && typeof s.id === 'string' && s.traceId.length > 0 && s.id.length > 0;

When it happens

Trigger: Calling ensureV2TraceData on an array whose first element is missing traceId or id, e.g. [{name:"op"}], [{}], or an array of strings/numbers. Falsy values (empty string, undefined, null) also trigger it.

Common situations: Array of annotation objects or log entries mistakenly fed as spans; truncated/partial JSON where fields were dropped; a list of parsed CSV rows or heterogeneous objects; test fixtures with incomplete span shapes.

Related errors

• input is not a list
• v1 format is not supported. For help, contact https://gitter
• 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/a2979eb02c9c424d. Report an issue: GitHub.