What causes "Expected a List type to have exactly one child" in lancedb/lancedb?

Ensure `children` contains exactly one element field object.

lancedb/lancedb · error · Error

Expected a List type to have exactly one child

Error message

Expected a List type to have exactly one child

What it means

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.

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}).

Example fix

// before
sanitizeList({ children: [itemField, extraField] });
// after
sanitizeList({ children: [itemField] });

Defensive patterns

Strategy: validation

Validate before calling

function assertSingleChildList(t) {
  if (!Array.isArray(t?.children) || t.children.length !== 1) {
    throw new TypeError('list type requires exactly one child field');
  }
}

Type guard

function isSingleChildList(t: object): t is { children: [unknown] } {
  return Array.isArray((t as any).children) && (t as any).children.length === 1;
}

Try / catch

try {
  const type = sanitizeList(typeLike);
} catch (e) {
  if (e.message.includes('exactly one child')) {
    // the descriptor is a Struct/Union-like shape; reroute to the right sanitizer
  }
  throw e;
}

Prevention

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.

When it happens

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

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

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of lancedb/lancedb@c7b051aff7 (2026-09-08). Data as JSON: /api/errors/f1ec97ae4efa9d07. Report an issue: GitHub.

Appendix: source

Thrown at nodejs/lancedb/sanitize.ts:223

  }
  return new Interval(typeLike.unit);
}

export function sanitizeList(typeLike: object) {
  return sanitizeListWithContext(typeLike, createSanitizationContext());
}

function sanitizeListWithContext(
  typeLike: object,
  context: SanitizationContext,
) {
  if (!("children" in typeLike) || !Array.isArray(typeLike.children)) {
    throw Error(
      "Expected a List type to have an array-like `children` property",
    );
  }
  if (typeLike.children.length !== 1) {
    throw Error("Expected a List type to have exactly one child");
  }
  return new List(sanitizeFieldWithContext(typeLike.children[0], context));
}

export function sanitizeStruct(typeLike: object) {
  return sanitizeStructWithContext(typeLike, createSanitizationContext());
}

function sanitizeStructWithContext(
  typeLike: object,
  context: SanitizationContext,
) {
  if (!("children" in typeLike) || !Array.isArray(typeLike.children)) {
    throw Error(
      "Expected a Struct type to have an array-like `children` property",
    );
  }
  return new Struct(

View on GitHub (pinned to c7b051aff7)