drizzle-team/drizzle-orm · error · Error

Invalid relation "${relation.fieldName}" for table "${it.sch

Error message

Invalid relation "${relation.fieldName}" for table "${it.schema ? `${it.schema}.${it.dbName}` : it.dbName}"

What it means

A catch-all wrapper around `normalizeRelation` and the dialect/relation-type checks. Any exception during relation normalization (ambiguous fields, mismatched column counts, unsupported dialect, non-One/Many) is re-thrown with a message naming the offending `relation.fieldName` and its parent table. This is the user-facing error for a structurally broken relation.

Source

Thrown at drizzle-kit/src/serializer/studio.ts:574

						type = 'one';
					} else if (is(rel, Many)) {
						type = 'many';
					} else {
						throw new Error('unsupported relation type');
					}

					return {
						name,
						type,
						table: it.dbName,
						schema: it.schema || 'public',
						columns: fields,
						refTable: refTableName,
						refSchema: refSchema || 'public',
						refColumns: refColumns,
					};
				} catch {
					throw new Error(
						`Invalid relation "${relation.fieldName}" for table "${
							it.schema ? `${it.schema}.${it.dbName}` : it.dbName
						}"`,
					);
				}
			})
		)
		.flat();
	return relations;
};

const init = z.object({
	type: z.literal('init'),
});

const proxySchema = z.object({
	type: z.literal('proxy'),
	data: z.object({

View on GitHub (pinned to b7862528fd)

Solutions

1. Open the relation named in the message and verify `fields` and `references` have equal length and valid columns.
2. Add `relationName` to disambiguate multiple relations between the same two tables.
3. Re-run Studio; if it persists, temporarily comment the named relation to confirm the cause.

Example fix

// before
one(posts, { fields: [users.id], references: [posts.authorId, posts.coAuthorId] }), // length mismatch
// after
one(posts, { fields: [users.id], references: [posts.authorId] }),

// Validate one() fields/references length parity before Studio
import type { AnyColumn } from 'drizzle-orm';
function assertOneRelation(fields: AnyColumn[], references: AnyColumn[]) {
  if (fields.length !== references.length) {
    throw new Error('one() fields and references length mismatch');
  }
}

function isAmbiguousRelationPair(a: { table: string }, b: { table: string }) {
  return a.table === b.table;
}

try {
  const rels = extractRelations(config);
} catch (e) {
  const m = (e as Error).message.match(/Invalid relation "(\w+)" for table "([\w.]+)"/);
  if (m) console.error(`Fix relation ${m[1]} on ${m[2]}`);
  throw e;
}

When it happens

Trigger: Defining a `one()` relation whose `fields` and `references` arrays have different lengths, point at the wrong table, or are ambiguous (multiple relations to the same table without `relationName`). Also reached via errors 3/4 when the inner check fails.

Common situations: Ambiguous relations between two tables that share two foreign keys (the docs' disambiguation case), schema refactors that leave dangling references, or copy-paste errors in `fields`/`references`.

Related errors

• unsupported relation type
• unsupported dialect
• Transaction not supported
• Custom default not found for ${column.schema}.${column.table
• Unknown type: ${type}

AI-assisted analysis of drizzle-team/drizzle-orm@b7862528fd (2026-08-03). Data as JSON: /data/errors/b1780a2c53a320df.json. Report an issue: GitHub.