lancedb/lancedb · error · Error

Expected a Struct type to have an array-like `children`…

Error message

Expected a Struct type to have an array-like `children` property

What it means

sanitizeStructWithContext validates that a serialized Struct type has a `children` property that is an array; each element is recursively sanitized into the struct's fields. Missing or non-array children mean the descriptor cannot represent an Arrow Struct, so it throws before constructing an invalid type.

Solutions

Provide `children` as an array of field-like objects, one per struct field.
Pass a real arrow.Struct([...fields]) instance instead of a plain object.
Convert keyed-object serializations to an explicit field array before sanitizing.

Example fix

// before
sanitizeStruct({ name: 'id', name: 'value' });
// after
sanitizeStruct({ children: [{ name: 'id', type: { typeId: 2 } }, { name: 'value', type: { typeId: 2 } }] });

Defensive patterns

Strategy: validation

Validate before calling

function assertStructLike(t) {
  if (!Array.isArray(t?.children)) {
    throw new TypeError('struct type requires children array of fields');
  }
}

Type guard

function isStructLike(t: object): t is { children: unknown[] } {
  return "children" in t && Array.isArray((t as any).children);
}

Try / catch

try {
  const type = sanitizeStruct(typeLike);
} catch (e) {
  if (e.message.includes('Struct type to have an array-like')) {
    // convert keyed-object struct serialization to a field array, then retry
  }
  throw e;
}

Prevention

Represent struct fields as an array, not a keyed object, in your serialization format.
Use arrow.Struct with an explicit Field list rather than ad-hoc objects.
Round-trip struct-containing schemas in tests whenever serialization code changes.

When it happens

Trigger: sanitizeStruct({}) (no children), sanitizeStruct({children: 'name,type'}), or children as a map/object rather than an array; also reached via sanitizeTypeById on typeId Struct.

Common situations: Struct schemas serialized as keyed objects {fieldName: type} instead of arrays of fields by custom serializers; nested metadata dropped during JSON round-trip; hand-built descriptors forgetting the fields array.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

Thrown at nodejs/lancedb/sanitize.ts:237

      "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(
    typeLike.children.map((child) => sanitizeFieldWithContext(child, context)),
  );
}

export function sanitizeUnion(typeLike: object) {
  return sanitizeUnionWithContext(typeLike, createSanitizationContext());
}

function sanitizeUnionWithContext(
  typeLike: object,
  context: SanitizationContext,
) {
  if (
    !("typeIds" in typeLike) ||

View on GitHub (pinned to c7b051aff7)