{"record":{"id":"f1ec97ae4efa9d07","repo":"lancedb/lancedb","slug":"expected-a-list-type-to-have-exactly-one-child","errorCode":null,"errorMessage":"Expected a List type to have exactly one child","messagePattern":"Expected a List type to have exactly one child","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"nodejs/lancedb/sanitize.ts","lineNumber":223,"sourceCode":"  }\n  return new Interval(typeLike.unit);\n}\n\nexport function sanitizeList(typeLike: object) {\n  return sanitizeListWithContext(typeLike, createSanitizationContext());\n}\n\nfunction sanitizeListWithContext(\n  typeLike: object,\n  context: SanitizationContext,\n) {\n  if (!(\"children\" in typeLike) || !Array.isArray(typeLike.children)) {\n    throw Error(\n      \"Expected a List type to have an array-like `children` property\",\n    );\n  }\n  if (typeLike.children.length !== 1) {\n    throw Error(\"Expected a List type to have exactly one child\");\n  }\n  return new List(sanitizeFieldWithContext(typeLike.children[0], context));\n}\n\nexport function sanitizeStruct(typeLike: object) {\n  return sanitizeStructWithContext(typeLike, createSanitizationContext());\n}\n\nfunction sanitizeStructWithContext(\n  typeLike: object,\n  context: SanitizationContext,\n) {\n  if (!(\"children\" in typeLike) || !Array.isArray(typeLike.children)) {\n    throw Error(\n      \"Expected a Struct type to have an array-like `children` property\",\n    );\n  }\n  return new Struct(","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/lancedb/lancedb/blob/c7b051aff7039333a3f61b79217246c27676806a/nodejs/lancedb/sanitize.ts#L205-L241","documentation":"After confirming `children` is an array, sanitizeListWithContext enforces that an Arrow List type has exactly one child — the element field. Arrow lists are monomorphic: a list has precisely one value field. Zero or multiple children mean the descriptor is corrupt or not a List type, so the sanitizer throws.","triggerScenarios":"sanitizeList({children: []}) (empty array) or sanitizeList({children: [fieldA, fieldB]}) (two children); also via sanitizeTypeById when a Struct/Union-like descriptor is misrouted to the List sanitizer.","commonSituations":"Manually constructed list descriptors with multiple element fields (confusing List with Struct); empty children after filtering during serialization; using a serialized Struct's children array where a List was expected.","solutions":["Ensure `children` contains exactly one element field object.","If you need multiple child fields, use a Struct or Union type instead of a List.","If the array is empty, add the element field (typically {name:'item', type:..., nullable:true})."],"exampleFix":"// before\nsanitizeList({ children: [itemField, extraField] });\n// after\nsanitizeList({ children: [itemField] });","handlingStrategy":"validation","validationCode":"function assertSingleChildList(t) {\n  if (!Array.isArray(t?.children) || t.children.length !== 1) {\n    throw new TypeError('list type requires exactly one child field');\n  }\n}","typeGuard":"function isSingleChildList(t: object): t is { children: [unknown] } {\n  return Array.isArray((t as any).children) && (t as any).children.length === 1;\n}","tryCatchPattern":"try {\n  const type = sanitizeList(typeLike);\n} catch (e) {\n  if (e.message.includes('exactly one child')) {\n    // the descriptor is a Struct/Union-like shape; reroute to the right sanitizer\n  }\n  throw e;\n}","preventionTips":["Use Struct or Union when a nested type genuinely has multiple fields.","Never filter children during serialization — an empty children array is invalid for List.","Validate one-child invariant when converting external nested-type models to arrow."],"tags":["typescript","schema","arrow","list"],"backgroundTag":"invalid-argument-value","analyzedSha":"c7b051aff7039333a3f61b79217246c27676806a","analyzedAt":"2026-09-08T23:42:37.579Z","contentChangedAt":"2026-09-08T23:42:37.579Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}