What causes "input is not a list" in openzipkin/zipkin?

Pass a non-empty JSON array of v2 span objects, e.g. [{"traceId":"...","id":"...",...}] — wrap a single span in [ ] if needed.

openzipkin/zipkin · error · Error

input is not a list

Error message

input is not a list

What it means

Thrown by zipkin-lens's ensureV2TraceData when the value passed as a trace is not a non-empty JavaScript array. Zipkin's UI trace pipeline expects a List<Span> (JSON array of span objects) in the v2 JSON format; anything else (an object, a string, null, or an empty array) fails this precondition check immediately. The function exists to fail fast before downstream tree-building code assumes array semantics.

Source

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

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

View on GitHub (pinned to 878ce2a1fa)

Solutions

Pass a non-empty JSON array of v2 span objects, e.g. [{"traceId":"...","id":"...",...}] — wrap a single span in [ ] if needed.
If the input is a JSON string, JSON.parse it before calling ensureV2TraceData.
If the data came from a v1 endpoint or a nested document shape, extract the actual spans array field before validation.
Check the upstream fetch: an error/empty response body should be handled before reaching trace rendering.

Example fix

// before
const trace = await resp.json(); // resp returned a single object, not a list
ensureV2TraceData(trace); // throws 'input is not a list'

// after
const data = await resp.json();
const trace = Array.isArray(data) ? data : [data];
ensureV2TraceData(trace);

Defensive patterns

Strategy: type-guard

Validate before calling

const isNonEmptyArray = (v) => Array.isArray(v) && v.length > 0;
if (!isNonEmptyArray(trace)) throw new TypeError('expected non-empty span array');

Type guard

const isSpanList = (v) => Array.isArray(v) && v.length > 0 && typeof v[0] === 'object' && v[0] !== null;

Prevention

Always JSON.parse API bodies and assert Array.isArray before handing data to trace rendering.
Handle fetch error/empty responses before the trace pipeline.
Keep test fixtures as real arrays of v2 spans copied from a live Zipkin response.

When it happens

Trigger: Calling ensureV2TraceData(trace) (directly or via the lens trace-viewer entry point) with: a single span object instead of a one-element array, a parsed JSON document that is an object (e.g. a v1 Trace document or an error-response object), a string of undecoded JSON, or an empty array [].

Common situations: Passing API response data from /trace/{id} without parsing or after wrapping incorrectly; feeding a v1-format JSON structure that is a single object; a fetch that returned an error body which is then forwarded as trace data; feeding data from a test fixture that is an object map keyed by span id.

Related errors

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