What causes "Table "${referencedTableTsName}" not found in schema" in drizzle-team/drizzle-orm?

Always build the relational schema via drizzle({ schema }) with a single complete schema object exported from one module.

drizzle-team/drizzle-orm · error · Error

Table "${referencedTableTsName}" not found in schema

Error message

Table "${referencedTableTsName}" not found in schema

What it means

normalizeRelation() throws when the referenced table's TypeScript name was found in tableNamesMap but is absent from the actual schema config object. This indicates an inconsistency between the table-name map and the relational schema built by extractTablesRelationalConfig - typically a partial or mismatched schema where a relation target exists by name but its config was not registered.

Source

Thrown at drizzle-orm/src/relations.ts:580

	relation: Relation,
): NormalizedRelation {
	if (is(relation, One) && relation.config) {
		return {
			fields: relation.config.fields,
			references: relation.config.references,
		};
	}

	const referencedTableTsName = tableNamesMap[getTableUniqueName(relation.referencedTable)];
	if (!referencedTableTsName) {
		throw new Error(
			`Table "${relation.referencedTable[Table.Symbol.Name]}" not found in schema`,
		);
	}

	const referencedTableConfig = schema[referencedTableTsName];
	if (!referencedTableConfig) {
		throw new Error(`Table "${referencedTableTsName}" not found in schema`);
	}

	const sourceTable = relation.sourceTable;
	const sourceTableTsName = tableNamesMap[getTableUniqueName(sourceTable)];
	if (!sourceTableTsName) {
		throw new Error(
			`Table "${sourceTable[Table.Symbol.Name]}" not found in schema`,
		);
	}

	const reverseRelations: Relation[] = [];
	for (
		const referencedTableRelation of Object.values(
			referencedTableConfig.relations,
		)
	) {
		if (
			(relation.relationName

View on GitHub (pinned to b7862528fd)

Solutions

Always build the relational schema via drizzle({ schema }) with a single complete schema object exported from one module.
Audit for duplicate table definitions (same table name defined in two files) and consolidate to a single source.
Disable aggressive tree-shaking for the schema module or mark schema exports as side-effectful if the bundler drops them.

Example fix

// before: schema map and relations out of sync
const db = drizzle(client, { schema: { users, posts } }); // but relations reference a 'comments' table not in schema

// after: single complete schema
import * as schema from './schema';
const db = drizzle(client, { schema });

Defensive patterns

Strategy: validation

Validate before calling

// Ensure the relational schema is built from a single complete schema object
// so tableNamesMap and the schema config stay consistent.
import * as schema from './schema';

function assertNoTableDuplicates(schema: Record<string, any>) {
  const seen = new Map<string, string>();
  for (const [key, v] of Object.entries(schema)) {
    if (v?.[Symbol.for('drizzle:entityKind')] === 'Table') {
      const unique = v[Symbol.for('drizzle:Name')];
      if (seen.has(unique)) {
        throw new Error(`Duplicate table "${unique}" (keys: ${seen.get(unique)}, ${key})`);
      }
      seen.set(unique, key);
    }
  }
}
assertNoTableDuplicates(schema);
const db = drizzle(client, { schema });

Type guard

// Detect that tableNamesMap and schema disagree by checking every
// relation target key resolves to a config entry.
function schemaIsComplete(schema: Record<string, any>): boolean {
  return Object.values(schema).every((v) => v && typeof v === 'object');
}

Try / catch

try {
  await db.query.users.findFirst();
} catch (e) {
  if (e instanceof Error && /not found in schema/.test(e.message)) {
    // rebuild schema as a single barrel export and re-pass
  } else throw e;
}

Prevention

Build relational config only via drizzle({ schema }) with one consolidated schema module.
Eliminate duplicate table definitions across files.
Mark schema modules as side-effectful in bundler config to prevent tree-shaking dropping tables.

When it happens

Trigger: Passing two different schema objects to tableNamesMap and the relational schema, or a relations definition whose target table key differs from what extractTablesRelationalConfig produced. Mixed imports where the same logical table is represented by two different objects.

Common situations: Build/bundler tree-shaking dropping a table from the schema map but keeping it in relations. Manual construction of relational config instead of using drizzle({schema}). Duplicated table definitions across files.

Related errors

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