What causes "At least one record or a schema needs to be provided" in lancedb/lancedb?

Provide a schema: pass options.schema (an apache-arrow Schema or schema-like object) when data is empty.

At least one record or a schema needs to be provided

Error message

At least one record or a schema needs to be provided

What it means

makeArrowTable needs something to build a table from. If the data array is empty and no schema option is supplied, it cannot infer an Arrow schema and throws. This guards against silently creating a table with no columns.

Solutions

Provide a schema: pass options.schema (an apache-arrow Schema or schema-like object) when data is empty.
Use the dedicated helper makeEmptyTable(schema) instead of calling makeArrowTable([]).
Ensure the data array is non-empty before calling, e.g. filter out empty batches before insertion.
If the schema is known only from existing data, open/read the existing table first and reuse its schema.

Example fix

// before
await db.createTable("items", []);
// after
import * as arrow from "apache-arrow";
await db.createTable("items", [], { schema: new arrow.Schema([
  new arrow.Field("id", new arrow.Int32()),
  new arrow.Field("name", new arrow.Utf8()),
]) });

Defensive patterns

Strategy: validation

Validate before calling

if (rows.length === 0 && !options?.schema) {
  throw new Error("Provide rows or an explicit schema before creating the table");
}

Type guard

function hasSchema(o?: { schema?: unknown }): o is { schema: object } {
  return o?.schema != null;
}

Try / catch

try {
  await db.createTable(name, rows, opts);
} catch (e) {
  if (e.message.includes("At least one record or a schema")) {
    await db.createTable(name, rows, { ...opts, schema: knownSchema });
  } else throw e;
}

Prevention

Never call createTable/makeArrowTable with a possibly-empty array without a schema.
Use makeEmptyTable(schema) for intentional empty tables.
Guard batch pipelines to skip empty batches or supply a schema up front.

When it happens

Trigger: Calling makeArrowTable([]) (or table/db.createTable with an empty records array) without passing options.schema or options.schemaLike.

Common situations: Developers inserting records from an upstream API that returned an empty list, or looping over batches where the first batch is empty and they expect LanceDB to infer the schema from later batches.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at nodejs/lancedb/arrow.ts:427

  if (opt.schema !== undefined && opt.schema !== null) {
    schema = sanitizeSchema(opt.schema);
    schema = validateSchemaEmbeddings(
      schema as Schema,
      data,
      options?.embeddingFunction,
    );
  }

  let schemaMetadata = schema?.metadata || new Map<string, string>();
  if (metadata !== undefined) {
    schemaMetadata = new Map([...schemaMetadata, ...metadata]);
  }

  if (
    data.length === 0 &&
    (options?.schema === undefined || options?.schema === null)
  ) {
    throw new Error("At least one record or a schema needs to be provided");
  } else if (data.length === 0) {
    if (schema === undefined) {
      throw new Error("A schema must be provided if data is empty");
    } else {
      schema = new Schema(schema.fields, schemaMetadata);
      return new ArrowTable(schema);
    }
  }

  let inferredSchema = inferSchema(data, schema, opt);
  inferredSchema = new Schema(inferredSchema.fields, schemaMetadata);

  const finalColumns: Record<string, Vector> = {};
  for (const field of inferredSchema.fields) {
    finalColumns[field.name] = transposeData(data, field);
  }

  return new ArrowTable(inferredSchema, finalColumns);

View on GitHub (pinned to c7b051aff7)