{"record":{"id":"3985ee0751a206a2","repo":"lancedb/lancedb","slug":"expected-a-schema-but-object-was-null-undefined","errorCode":null,"errorMessage":"Expected a Schema but object was null/undefined","messagePattern":"Expected a Schema but object was null/undefined","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nodejs/lancedb/sanitize.ts","lineNumber":627,"sourceCode":" * Convert something schemaLike into a Schema instance\n *\n * This method is often needed even when the caller is using a Schema\n * instance because they might be using a different instance of apache-arrow\n * than lancedb is using.\n */\nexport function sanitizeSchema(schemaLike: SchemaLike): Schema {\n  return sanitizeSchemaWithContext(schemaLike, createSanitizationContext());\n}\n\nfunction sanitizeSchemaWithContext(\n  schemaLike: SchemaLike,\n  context: SanitizationContext,\n): Schema {\n  if (schemaLike instanceof Schema) {\n    return schemaLike;\n  }\n  if (typeof schemaLike !== \"object\" || schemaLike === null) {\n    throw Error(\"Expected a Schema but object was null/undefined\");\n  }\n  if (!(\"fields\" in schemaLike)) {\n    throw Error(\n      \"The schema passed in does not appear to be a schema (no 'fields' property)\",\n    );\n  }\n  let metadata;\n  if (\"metadata\" in schemaLike) {\n    metadata = sanitizeMetadata(schemaLike.metadata);\n  }\n  if (!Array.isArray(schemaLike.fields)) {\n    throw Error(\n      \"The schema passed in had a 'fields' property but it was not an array\",\n    );\n  }\n  const sanitizedFields = schemaLike.fields.map((field) =>\n    sanitizeFieldWithContext(field, context),\n  );","sourceCodeStart":609,"sourceCodeEnd":645,"githubUrl":"https://github.com/lancedb/lancedb/blob/c7b051aff7039333a3f61b79217246c27676806a/nodejs/lancedb/sanitize.ts#L609-L645","documentation":"sanitizeSchemaWithContext accepts either a real apache-arrow `Schema` instance (returned as-is) or a schema-like plain object. If the input is not an object at all (null, undefined, a primitive), it cannot be a schema, so this error is thrown immediately. It exists to give a clear message instead of a cryptic `Cannot read properties of null` from the subsequent property checks.","triggerScenarios":"Calling sanitizeSchema/schema (or table APIs that call parseTableData -> sanitizeTable) with `undefined` because an optional schema variable was never assigned; passing `null` explicitly; passing a non-object such as a string of serialized JSON instead of the parsed object.","commonSituations":"Loading a schema asynchronously and using it before the promise resolves; a failed JSON.parse silently yielding null and being forwarded; destructuring mistakes passing the wrong variable; IPC handlers receiving `undefined` payloads.","solutions":["Check the value is non-null before calling: `if (!schemaLike) throw ...` or pass a real `Schema` instance.","If the schema came from JSON, parse it (`JSON.parse`) rather than passing the raw string.","If the schema is loaded async, `await` the promise before use.","Construct the schema with `new Schema(fields)` from apache-arrow so it takes the fast path and bypasses sanitization."],"exampleFix":"// before\nconst t = table.schema.then(s => sanitizeSchema(s))  // schema still undefined here\nsanitizeSchema(maybeSchema);\n// after\nif (maybeSchema == null) throw new Error('schema is required');\nconst s = await loadSchema();\nsanitizeSchema(s);","handlingStrategy":"type-guard","validationCode":"if (schemaLike == null || typeof schemaLike !== 'object') {\n  throw new Error(`expected a schema object, got ${schemaLike === null ? 'null' : typeof schemaLike}`);\n}","typeGuard":"import { Schema } from 'apache-arrow';\nfunction isSchemaLike(v: unknown): v is Schema | { fields: unknown[] } {\n  return v instanceof Schema || (typeof v === 'object' && v !== null);\n}","tryCatchPattern":"try {\n  const schema = sanitizeSchemaWithContext(maybeSchema, ctx);\n} catch (e) {\n  if (e.message.includes('object was null/undefined')) {\n    console.error('Schema was never populated; check async loading and JSON parsing');\n  }\n  throw e;\n}","preventionTips":["Await all promises producing schemas before use","Check JSON.parse results for null on empty/invalid input","Pass real Schema instances to skip sanitization entirely","Fail fast with an explicit null check at API boundaries"],"tags":["schema","null","validation","arrow"],"backgroundTag":"null-argument","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"}