lancedb/lancedb · error

The schema passed in does not appear to be a schema (no…

Error message

The schema passed in does not appear to be a schema (no 'fields' property)

What it means

sanitizeSchemaWithContext treats an object as schema-like only if it has a `fields` property. An object without `fields` (or with it misspelled) is not a recognizable Schema, so this error is thrown. This is a duck-typing guard for schema objects that crossed a serialization boundary and lost their class identity.

Solutions

1. Wrap your fields in the expected shape: `{ fields: [/* Field-like objects */], metadata: {...} }`.
2. Prefer constructing a real `new Schema(fields)` from apache-arrow — instances are returned unchanged.
3. Verify the object actually holds fields: log `Object.keys(obj)` and check for `fields`.
4. If you have a Record of columns, convert it: `{ fields: Object.entries(cols).map(([name, type]) => new Field(name, type, true)) }`.

Example fix

// before
const s = { item: new Field('item', new Utf8(), true) };
sanitizeSchema(s);
// after
const s = { fields: [new Field('item', new Utf8(), true)] };
sanitizeSchema(s);

if (schemaLike != null && typeof schemaLike === 'object' && !('fields' in schemaLike)) {
  throw new Error('schema-like object must have a `fields` array property');
}

function isSchemaLikeObject(v: unknown): v is { fields: unknown[]; metadata?: unknown } {
  return typeof v === 'object' && v !== null && 'fields' in v;
}

try {
  const schema = sanitizeSchemaWithContext(candidate, ctx);
} catch (e) {
  if (e.message.includes("no 'fields' property")) {
    console.error('Object keys:', Object.keys(candidate));
  }
  throw e;
}

When it happens

Trigger: Passing a plain object like `{ metadata: {...} }` or a single Field object where a Schema was expected; passing a Record<string, Field> mapping (column-name keys) instead of `{ fields: [...] }`; typos like `field` or `columns` instead of `fields`.

Common situations: Hand-building a schema object and using the wrong key name; passing the output of a different library's schema representation (e.g. a JSON column map); accidentally passing a table or record batch where a schema was required.

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

• Expected a Dictionary type to have an `dictionary` property
• Expected a Dictionary type to have an `id` property
• Expected a Dictionary type to have an `indices` property
• Expected a Dictionary type to have an `isOrdered` property
• Expected a Duration type to have a `unit` property

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

Appendix: source

Thrown at nodejs/lancedb/sanitize.ts:630

 * instance because they might be using a different instance of apache-arrow
 * than lancedb is using.
 */
export function sanitizeSchema(schemaLike: SchemaLike): Schema {
  return sanitizeSchemaWithContext(schemaLike, createSanitizationContext());
}

function sanitizeSchemaWithContext(
  schemaLike: SchemaLike,
  context: SanitizationContext,
): Schema {
  if (schemaLike instanceof Schema) {
    return schemaLike;
  }
  if (typeof schemaLike !== "object" || schemaLike === null) {
    throw Error("Expected a Schema but object was null/undefined");
  }
  if (!("fields" in schemaLike)) {
    throw Error(
      "The schema passed in does not appear to be a schema (no 'fields' property)",
    );
  }
  let metadata;
  if ("metadata" in schemaLike) {
    metadata = sanitizeMetadata(schemaLike.metadata);
  }
  if (!Array.isArray(schemaLike.fields)) {
    throw Error(
      "The schema passed in had a 'fields' property but it was not an array",
    );
  }
  const sanitizedFields = schemaLike.fields.map((field) =>
    sanitizeFieldWithContext(field, context),
  );
  return new Schema(sanitizedFields, metadata);
}

View on GitHub (pinned to c7b051aff7)