{"record":{"id":"db537997050d5aff","repo":"openzipkin/zipkin","slug":"input-is-not-a-list","errorCode":null,"errorMessage":"input is not a list","messagePattern":"input is not a list","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"zipkin-lens/src/util/trace.js","lineNumber":7,"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:","sourceCodeStart":1,"sourceCodeEnd":25,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-lens/src/util/trace.js#L1-L25","documentation":"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.","triggerScenarios":"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 [].","commonSituations":"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.","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."],"exampleFix":"// before\nconst trace = await resp.json(); // resp returned a single object, not a list\nensureV2TraceData(trace); // throws 'input is not a list'\n\n// after\nconst data = await resp.json();\nconst trace = Array.isArray(data) ? data : [data];\nensureV2TraceData(trace);","handlingStrategy":"type-guard","validationCode":"const isNonEmptyArray = (v) => Array.isArray(v) && v.length > 0;\nif (!isNonEmptyArray(trace)) throw new TypeError('expected non-empty span array');","typeGuard":"const isSpanList = (v) => Array.isArray(v) && v.length > 0 && typeof v[0] === 'object' && v[0] !== null;","tryCatchPattern":null,"preventionTips":["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."],"tags":["zipkin","javascript","validation","trace-data"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}