@@ -0,0 +1,23 @@
+---
+'@objectstack/rest': patch
+---
+
+fix(rest): an import row names the column the engine refused, and a missing database column is no longer called an unknown field (#20701)
+
+**`POST /api/v1/data/:object/import` — a failed row names its column.** A row the
+engine refuses with `INVALID_FIELD` (a column that names no field of the object)
+now carries `field` with that column, on the dry run and on the commit alike. It
+used to carry only `code: 'INVALID_FIELD'`, while `POST /api/v1/data/:object`
+named the field for the same key. The row reads the error's own `field` when no
+field-level finding names one; a field-level finding still wins. A unique
+conflict row now names its column too, when the database said which column it
+was, as the `409` does.
+
+**A missing database column says what the database said.** When the database
+reports that a table has no column for a field, the `400 INVALID_FIELD` answer
+now reads "The database table of object 'X' has no column for field 'f'. If the
+object declares 'f', its database schema has drifted from the metadata: run
+'os migrate' to reconcile." It used to read "Unknown field 'f'", which was false
+for a field the object declares: the engine refuses an undeclared key itself,
+before the database is reached, and keeps its own "Unknown field" wording for
+that case. `code`, `status`, `field` and `object` are unchanged.
@@ -1249,9 +1249,9 @@ function structuredCodeAnswer(
     // [#4134] Unknown field named by a READ — the protocol's list normalizer
     // refusing to lower a query parameter that matches no field into an
     // implicit filter that could only ever match zero rows. Emitted in the SAME
-    // envelope as the driver-string branch below (which catches the write-path
-    // form of the identical mistake), so one condition has one wire shape no
-    // matter which layer noticed it. Must precede the generic 4xx passthrough,
+    // envelope as the driver-string branch below (which classifies a driver's
+    // missing-column text, and since #20701 says so rather than "Unknown
+    // field"), so one wire shape serves both. Must precede the generic 4xx passthrough,
     // which would ship the message but drop `field`.
     // [commit 6d178a408] `!isSandboxOrigin`: the same clause as the arm above, and here
     // it carries the sentence reason TOO — this arm really does ship
@@ -1772,6 +1772,18 @@ function classifyDataError(error: any, object?: string): { status: number; body:
     // a legal missing-TABLE phrase as a substring, and `service-analytics` and
     // `metadata` each had to repair the same superstring hole. Same regex as
     // before, same position last in the chain — only its owner moved.
+    //
+    // [#20701] The sentence says what the DATABASE said — the table has no
+    // such column — and never "Unknown field". This branch sees only the
+    // driver's text, not the object's field map, while the engine's
+    // declared-field door refuses an undeclared write key before any driver
+    // runs, in its own words, and the read doors gate undeclared filter names
+    // the same way. So a request that gets this far usually names a field the
+    // object DECLARES whose column is missing: metadata and the physical
+    // schema have drifted, and "Unknown field" sent the author hunting for a
+    // typo in a correct declaration. (A formula column was the common case;
+    // the engine strips that value now, reason `computed`.) `code`, `status`,
+    // `field` and `object` are unchanged.
     const unknownColumn =
         /has no column named\s+["'`]?([a-z0-9_]+)/i.exec(raw)?.[1] ??
         /no such column:\s*["'`]?([a-z0-9_.]+)/i.exec(raw)?.[1] ??
@@ -1783,8 +1795,10 @@ function classifyDataError(error: any, object?: string): { status: number; body:
             status: 400,
             body: {
                 error: field
-                    ? `Unknown field '${field}'${object ? ` on object '${object}'` : ''}`
-                    : 'Request references a field that does not exist',
+                    ? `The database table${object ? ` of object '${object}'` : ''} has no column for field '${field}'. `
+                        + `If the object declares '${field}', its database schema has drifted from the metadata: `
+                        + `run 'os migrate' to reconcile.`
+                    : 'The request references a column the database table does not have.',
                 code: 'INVALID_FIELD',
                 ...(field ? { field } : {}),
                 ...(object ? { object } : {}),
 
@@ -0,0 +1,205 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#20701] What the import row report and the driver-string branch say about
+ * a column, read through the public doors — `POST /api/v1/data/:object/import`
+ * (dry run and commit) and `POST /api/v1/data/:object` — over a REAL
+ * {@link ObjectQL} + {@link ObjectStackProtocolImplementation} + SQLite
+ * `:memory:`.
+ *
+ * Measured on the base (`ca5408c629`), with the engine half (#20805) already
+ * landed:
+ *
+ * | column | dry run | commit | `POST /data/:object` |
+ * |:--|:--|:--|:--|
+ * | undeclared `nope` | failed `INVALID_FIELD`, **no `field`** | failed `INVALID_FIELD`, **no `field`** | `400 INVALID_FIELD`, `field: 'nope'` |
+ * | declared `late`, no column (drift) | — | — | `400 INVALID_FIELD` "Unknown field 'late'" |
+ * | formula `doubled` / readonly `ro` | ok, created | ok, created | `201` + `droppedFields` |
+ * | writable `title` | ok, created | ok, created | `201` |
+ * | a `unique` value already held | — | failed `UNIQUE_VIOLATION`, **no `field`** | `409 UNIQUE_VIOLATION`, `field` |
+ *
+ * The first and last rows are `toFailedResult` reading `field` only off a
+ * `ValidationError` finding, while the engine's declared-field door and its
+ * `DuplicateRecordError` carry it on the envelope (`field`; the declared-field
+ * door puts the bare names in `fields`). The second is `mapDataError`'s
+ * driver-string branch calling a DECLARED field unknown.
+ *
+ * ⚠️ Not pinned here: the drop signal on the formula / readonly rows. The dry
+ * run's source, the protocol's `validateData`, returns no `droppedFields` at
+ * all, so the import cannot read one without a change outside this package
+ * (the card's report names it). The formula and readonly cells below pin only
+ * that both halves SUCCEED, which is the half of the card's pin that holds.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { ObjectQL } from '@objectstack/objectql';
+import { SqlDriver } from '@objectstack/driver-sql';
+import { ObjectStackProtocolImplementation } from '@objectstack/metadata-protocol';
+import { RestServer } from './rest-server';
+
+const OBJECT = 'proj_20701';
+
+const PROJ = {
+  name: OBJECT, label: 'Proj 20701', systemFields: false,
+  fields: {
+    id: { name: 'id', type: 'text' as const, primaryKey: true },
+    title: { name: 'title', type: 'text' as const },
+    n: { name: 'n', type: 'number' as const },
+    doubled: { name: 'doubled', type: 'formula' as const, expression: 'record.n * 2' },
+    ro: { name: 'ro', type: 'text' as const, readonly: true },
+  },
+};
+
+function createMockServer() {
+  const noop = () => {};
+  return { get: noop, post: noop, put: noop, delete: noop, patch: noop, use: noop, listen: async () => {}, close: async () => {} };
+}
+
+function makeRes() {
+  const res: any = {
+    write: () => true, end: () => {},
+    header: () => res,
+    status: (code: number) => { res._status = code; return res; },
+    json: (body: any) => { res._json = body; return res; },
+  };
+  return res;
+}
+
+const liveEngines: ObjectQL[] = [];
+afterEach(async () => {
+  while (liveEngines.length) {
+    try { await liveEngines.pop()?.destroy(); } catch { /* noop */ }
+  }
+});
+
+async function boot() {
+  const engine = new ObjectQL();
+  liveEngines.push(engine);
+  engine.registerDriver(new SqlDriver({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true }), true);
+  await engine.init();
+  engine.registry.registerObject(PROJ as any);
+  await engine.syncSchemas();
+  await engine.insert(OBJECT, { id: 'e1', title: 'existing', n: 1 } as any);
+
+  const protocol = new ObjectStackProtocolImplementation(engine as any);
+  const rest = new RestServer(createMockServer() as any, protocol as any, { api: { requireAuth: false } } as any);
+  (rest as any).resolveExecCtx = async () => ({ userId: 'test-user' });
+  rest.registerRoutes();
+  const call = async (method: string, path: string, body: unknown, object: string = OBJECT): Promise<{ status: number; body: any }> => {
+    const route = rest.getRoutes().find((r: any) => r.method === method && r.path === path);
+    expect(route, `${method} ${path}`).toBeDefined();
+    const res = makeRes();
+    await route!.handler({ params: { object }, body, query: {}, headers: {} } as any, res);
+    return { status: res._status ?? 200, body: res._json };
+  };
+  const importRows = (rows: Array<Record<string, unknown>>, opts: { dryRun: boolean; writeMode?: 'insert' | 'upsert' }) =>
+    call('POST', '/api/v1/data/:object/import', {
+      format: 'json', rows, dryRun: opts.dryRun,
+      ...(opts.writeMode === 'upsert' ? { writeMode: 'upsert', matchFields: ['id'] } : {}),
+    });
+  return { engine, call, importRows };
+}
+
+type Boot = Awaited<ReturnType<typeof boot>>;
+
+describe('[#20701] an unknown column fails the row on the dry run and on the commit alike, and both rows name it', () => {
+  let b: Boot;
+  beforeEach(async () => { b = await boot(); });
+
+  it.each([
+    ['insert', [{ title: 't', n: 2, nope: 5 }, { title: 'control', n: 3 }]],
+    ['upsert', [{ id: 'e1', title: 't', nope: 5 }, { id: 'n1', title: 'control', n: 3 }]],
+  ] as const)('writeMode %s', async (writeMode, rows) => {
+    for (const dryRun of [true, false]) {
+      const r = await b.importRows(rows as any, { dryRun, writeMode });
+      expect(r.status, JSON.stringify(r.body)).toBe(200);
+      expect(r.body.results[0], `dryRun=${dryRun}`).toMatchObject({
+        row: 1, ok: false, action: 'failed', code: 'INVALID_FIELD', field: 'nope',
+      });
+      // The second row is the control: the refusal is the row's, not the file's.
+      expect(r.body.results[1], `dryRun=${dryRun}`).toMatchObject({ row: 2, ok: true });
+      expect(r.body.errors, `dryRun=${dryRun}`).toBe(1);
+    }
+  });
+
+  it('the row names the same field the create door names for the same key', async () => {
+    const door = await b.call('POST', '/api/v1/data/:object', { title: 't', nope: 5 });
+    expect(door.status).toBe(400);
+    expect(door.body).toMatchObject({ code: 'INVALID_FIELD', field: 'nope' });
+    const commit = await b.importRows([{ title: 't', nope: 5 }], { dryRun: false });
+    expect(commit.body.results[0]).toMatchObject({ code: door.body.code, field: door.body.field });
+  });
+});
+
+describe('[#20701] a unique conflict row names the column the 409 names — the same envelope member', () => {
+  it('the engine\'s DuplicateRecordError carries `field`; the commit row reads it', async () => {
+    const b = await boot();
+    const UQ = 'uq_20701';
+    b.engine.registry.registerObject({
+      name: UQ, systemFields: false,
+      fields: { id: { name: 'id', type: 'text', primaryKey: true }, code: { name: 'code', type: 'text', unique: true } },
+    } as any);
+    await b.engine.syncSchemas();
+    await b.engine.insert(UQ, { id: 'a', code: 'X' } as any);
+    const door = await b.call('POST', '/api/v1/data/:object', { code: 'X' }, UQ);
+    expect(door.status).toBe(409);
+    expect(door.body).toMatchObject({ code: 'UNIQUE_VIOLATION', field: 'code' });
+    const commit = await b.call('POST', '/api/v1/data/:object/import', { format: 'json', rows: [{ code: 'X' }, { code: 'Y' }], dryRun: false }, UQ);
+    expect(commit.body.results[0]).toMatchObject({ row: 1, ok: false, action: 'failed', code: door.body.code, field: door.body.field });
+    expect(commit.body.results[1]).toMatchObject({ row: 2, ok: true, action: 'created' });
+  });
+});
+
+describe('[#20701] a writable column imports — the control', () => {
+  it('dry run and commit both create the row, and the commit stores it', async () => {
+    const b = await boot();
+    const preview = await b.importRows([{ id: 'w1', title: 'written', n: 4 }], { dryRun: true });
+    expect(preview.body).toMatchObject({ ok: 1, errors: 0, created: 1 });
+    expect(preview.body.results[0]).toMatchObject({ row: 1, ok: true, action: 'created' });
+    const commit = await b.importRows([{ id: 'w1', title: 'written', n: 4 }], { dryRun: false });
+    expect(commit.body).toMatchObject({ ok: 1, errors: 0, created: 1 });
+    expect(commit.body.results[0]).toMatchObject({ row: 1, ok: true, action: 'created', id: 'w1' });
+    const stored = await b.engine.findOne(OBJECT, { where: { id: 'w1' } });
+    expect(stored).toMatchObject({ title: 'written', n: 4, doubled: 8 });
+  });
+});
+
+describe('[#20701] a formula or readonly column: the dry run and the commit both succeed', () => {
+  it.each([
+    ['formula', { id: 'f1', title: 't', n: 2, doubled: 5 }],
+    ['readonly', { id: 'f1', title: 't', n: 2, ro: 'forged' }],
+  ] as const)('%s column', async (_label, row) => {
+    const b = await boot();
+    for (const dryRun of [true, false]) {
+      const r = await b.importRows([row], { dryRun });
+      expect(r.body, `dryRun=${dryRun}`).toMatchObject({ ok: 1, errors: 0, created: 1 });
+      expect(r.body.results[0], `dryRun=${dryRun}`).toMatchObject({ row: 1, ok: true, action: 'created' });
+    }
+    // The supplied value was not stored: the formula answers from `n`, and the readonly column stays empty.
+    const stored = await b.engine.findOne(OBJECT, { where: { id: 'f1' } });
+    expect(stored).toMatchObject({ n: 2, doubled: 4 });
+    expect(stored?.ro ?? null).toBeNull();
+  });
+});
+
+describe('[#20701] the driver-string branch does not call a declared field unknown', () => {
+  it('a declared field whose column is missing: 400 INVALID_FIELD naming it, and the sentence is the database\'s', async () => {
+    const b = await boot();
+    // The object declares `late` after the DDL ran, with no re-sync — metadata and the table have drifted.
+    b.engine.registry.registerObject({ ...PROJ, fields: { ...PROJ.fields, late: { name: 'late', type: 'text' as const } } } as any);
+    const r = await b.call('POST', '/api/v1/data/:object', { title: 't', late: 'x' });
+    expect(r.status, JSON.stringify(r.body)).toBe(400);
+    expect(r.body).toMatchObject({ code: 'INVALID_FIELD', field: 'late', object: OBJECT });
+    // The wording IS the fix here, so its first sentence is pinned.
+    expect(String(r.body.error).split('. ')[0]).toBe(`The database table of object '${OBJECT}' has no column for field 'late'`);
+    expect(String(r.body.error)).not.toMatch(/unknown field/i);
+  });
+
+  it('an undeclared key is still refused by the engine\'s own door, in its own words — the control', async () => {
+    const b = await boot();
+    const r = await b.call('POST', '/api/v1/data/:object', { title: 't', nope: 'x' });
+    expect(r.status).toBe(400);
+    expect(r.body).toMatchObject({ code: 'INVALID_FIELD', field: 'nope', object: OBJECT });
+    expect(String(r.body.error)).toContain("Unknown field 'nope'");
+  });
+});
@@ -340,17 +340,31 @@ export function sanitizeRowError(raw: unknown): string {
  * `DUPLICATE_RECORD` without being the engine's class keeps its own code, as it
  * does at the door. The engine's thrown identity is unchanged; only the row's
  * wire spelling moves.
+ *
+ * ## The column comes from the envelope's own `field` when no finding names one
+ *
+ * Not every refusal is a `ValidationError`. The engine's declared-field door
+ * throws the ADR-0112 envelope `INVALID_FIELD` / 400 with the column in its
+ * `field` member and the bare names in `fields` — strings, not findings — and
+ * `DuplicateRecordError` carries `field` when the dialect named the column.
+ * Reading `field` only off a finding left those rows naming no column, while
+ * `POST /data/:object` answered the same key with `field` set. Since
+ * `engine.validate` runs that door too, an unknown column now fails the dry
+ * run and the commit alike, and both rows name it. A finding still wins, as
+ * it does for `code`; an entry of `fields` that is not an object is not a
+ * finding.
  */
 function toFailedResult(rowNo: number, err: unknown): ImportRowResult {
-  const e = err as { code?: unknown; message?: unknown; fields?: unknown } | null | undefined;
-  const fields = Array.isArray(e?.fields) ? (e.fields as Array<{ field?: unknown; code?: unknown }>) : [];
-  const first = fields[0];
+  const e = err as { code?: unknown; message?: unknown; fields?: unknown; field?: unknown } | null | undefined;
+  const head: unknown = Array.isArray(e?.fields) ? e.fields[0] : undefined;
+  const first = head !== null && typeof head === 'object' ? (head as { field?: unknown; code?: unknown }) : undefined;
   const thrownCode = isEngineDuplicateRecordEnvelope(e) ? 'UNIQUE_VIOLATION' : e?.code;
   const code = first?.code ?? thrownCode ?? 'IMPORT_ROW_FAILED';
+  const field = first?.field != null && first.field !== '' ? first.field : e?.field;
   const message = sanitizeRowError(e?.message);
   return {
     row: rowNo, ok: false, action: 'failed', error: message, code: String(code),
-    ...(first?.field != null && first.field !== '' ? { field: String(first.field) } : {}),
+    ...(field != null && field !== '' ? { field: String(field) } : {}),
   };
 }