{"record":{"id":"bea07079d6925517","repo":"lancedb/lancedb","slug":"expected-a-union-type-to-have-an-array-like-child","errorCode":null,"errorMessage":"Expected a Union type to have an array-like `children` property","messagePattern":"Expected a Union type to have an array-like `children` property","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"nodejs/lancedb/sanitize.ts","lineNumber":264,"sourceCode":"export function sanitizeUnion(typeLike: object) {\n  return sanitizeUnionWithContext(typeLike, createSanitizationContext());\n}\n\nfunction sanitizeUnionWithContext(\n  typeLike: object,\n  context: SanitizationContext,\n) {\n  if (\n    !(\"typeIds\" in typeLike) ||\n    !(\"mode\" in typeLike) ||\n    typeof typeLike.mode !== \"number\"\n  ) {\n    throw Error(\n      \"Expected a Union type to have `typeIds` and `mode` properties\",\n    );\n  }\n  if (!(\"children\" in typeLike) || !Array.isArray(typeLike.children)) {\n    throw Error(\n      \"Expected a Union type to have an array-like `children` property\",\n    );\n  }\n\n  return new Union(\n    typeLike.mode,\n    // biome-ignore lint/suspicious/noExplicitAny: skip\n    typeLike.typeIds as any,\n    typeLike.children.map((child) => sanitizeFieldWithContext(child, context)),\n  );\n}\n\nexport function sanitizeTypedUnion(\n  typeLike: object,\n  // eslint-disable-next-line @typescript-eslint/naming-convention\n  UnionType: typeof DenseUnion | typeof SparseUnion,\n) {\n  return sanitizeTypedUnionWithContext(","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/lancedb/lancedb/blob/c7b051aff7039333a3f61b79217246c27676806a/nodejs/lancedb/sanitize.ts#L246-L282","documentation":"LanceDB's TypeScript sanitizer rebuilds Arrow schema types from plain serialized objects. When sanitizing a Union type, it requires the input object to have a `children` property that is an actual Array. This error is thrown when the property is missing or is not array-like, so the Union cannot be reconstructed with its child fields.","triggerScenarios":"Calling sanitizeTypeById (directly or via sanitizeUnion) on an object with an Arrow Union TypeCode whose `children` is absent, null, or not an Array — e.g. a hand-written or truncated JSON schema object like {mode: 0} with no children, or children set to a non-array value.","commonSituations":"Hand-authoring serialized schemas instead of round-tripping real Arrow types; an older client serializing union types without children; a migration/version change where the union serialization format dropped `children`; copy-paste errors omitting nested fields in a schema JSON file.","solutions":["Add an array `children` property containing the union's child Field objects.","Verify each entry of `children` is a serializable Field object the sanitizer can process.","Re-generate the schema from a real Arrow table/schema rather than hand-editing JSON.","Catch the error and log the offending type object to identify which union is malformed."],"exampleFix":"// before\nsanitizeTypeById(9, { mode: 0 });\n// after\nsanitizeTypeById(9, { mode: 0, children: [\n  new Field('int', new Int32(), true),\n  new Field('str', new Utf8(), true),\n] });","handlingStrategy":"type-guard","validationCode":"function assertUnionLike(t) {\n  if (!t || !Array.isArray(t.children)) {\n    throw new Error('Union type object must have an array `children` property');\n  }\n  return t;\n}\nassertUnionLike(typeLike); // call before sanitizeTypeById","typeGuard":"function isUnionLike(t) {\n  return typeof t === 'object' && t !== null && Array.isArray(t.children);\n}","tryCatchPattern":"try {\n  const union = sanitizeUnion(typeLike, context);\n} catch (e) {\n  if (String(e.message).includes('array-like `children`')) {\n    console.error('Malformed union type object:', JSON.stringify(typeLike));\n  } else { throw e; }\n}","preventionTips":["Always serialize schemas from real Arrow objects rather than writing JSON by hand.","Add a schema-shape validator that runs before sanitization in your pipeline.","Pin the LanceDB version so serialization formats do not drift unexpectedly.","Unit-test schema round-trips (type -> serialize -> sanitize) for union fields."],"tags":["typescript","schema","arrow","union"],"backgroundTag":"schema-validation-failed","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"}