lancedb/lancedb · error · Error

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

Error message

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

What it means

A Map type is rebuilt from a `children` array (containing the single entries struct field) plus `keysSorted`. This error is thrown when `children` is missing or not an Array, so the entries field cannot be recovered.

Solutions

Add an array `children` property containing the single entries Field.
Rename alternative keys (e.g. `entries`) to `children`.
Ensure the child is a valid serializable Field object.
Regenerate the schema by serializing a genuine Arrow Map type.

Example fix

// before
sanitizeTypeById(-1, { keysSorted: false, entries: f }); // Map code
// after
sanitizeTypeById(-1, { keysSorted: false, children: [entriesField] });

Defensive patterns

Strategy: type-guard

Validate before calling

function assertMapLike(t) {
  if (!t || !Array.isArray(t.children)) {
    throw new Error('Map type object must have an array `children` property');
  }
}
assertMapLike(typeLike); // before sanitizeTypeById

Type guard

function isMapLike(t) {
  return typeof t === 'object' && t !== null && Array.isArray(t.children);
}

Try / catch

try {
  const m = sanitizeMap(typeLike, context);
} catch (e) {
  if (String(e.message).includes('array-like `children`')) {
    console.error('Map type missing children:', JSON.stringify(typeLike));
  } else { throw e; }
}

Prevention

Serialize map types with `children` holding the single entries field.
Rename foreign keys like `entries` to `children` before sanitizing.
Keep map columns in schema round-trip tests.
Version-pin LanceDB to avoid serialization key drift.

When it happens

Trigger: Calling sanitizeTypeById (directly or via sanitizeMap) on a Map-like object without an array `children` — e.g. {} or {keysSorted: false, entries: f}, or children set to a non-array value.

Common situations: Hand-written schema JSON omitting the entries/children array; serializing from a library that stores map children under a different key (e.g. `entries`); version drift where serialization keys changed; typos in hand-edited schemas.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at nodejs/lancedb/sanitize.ts:358

  if (typeLike.children.length !== 1) {
    throw Error("Expected a FixedSizeList type to have exactly one child");
  }
  return new FixedSizeList(
    typeLike.listSize,
    sanitizeFieldWithContext(typeLike.children[0], context),
  );
}

export function sanitizeMap(typeLike: object) {
  return sanitizeMapWithContext(typeLike, createSanitizationContext());
}

function sanitizeMapWithContext(
  typeLike: object,
  context: SanitizationContext,
) {
  if (!("children" in typeLike) || !Array.isArray(typeLike.children)) {
    throw Error(
      "Expected a Map type to have an array-like `children` property",
    );
  }
  if (!("keysSorted" in typeLike) || typeof typeLike.keysSorted !== "boolean") {
    throw Error("Expected a Map type to have a `keysSorted` property");
  }
  if (typeLike.children.length !== 1) {
    throw Error("Expected a Map type to have exactly one child");
  }

  return new Map_(
    sanitizeFieldWithContext(typeLike.children[0], context),
    typeLike.keysSorted,
  );
}

export function sanitizeDuration(typeLike: object) {
  if (!("unit" in typeLike) || typeof typeLike.unit !== "number") {

View on GitHub (pinned to c7b051aff7)