drizzle-team/drizzle-orm · error · Error

Your "${f.path.join('->')}" field references a column "${tab

Error message

Your "${f.path.join('->')}" field references a column "${tableName}"."${f.field.name}", but the table "${tableName}" is not part of the query! Did you forget to join it?

What it means

An Error thrown by PgDialect.buildSelectQuery() (drizzle-orm/src/pg-core/dialect.ts:377) during query building. For each selected field, it checks that the field's column belongs either to the FROM table or to one of the joined aliases; if a selected column references a table that is neither the FROM table nor a join alias, it throws, telling you which field/path references which unjoined table.

Source

Thrown at drizzle-orm/src/pg-core/dialect.ts:377

		const fieldsList = fieldsFlat ?? orderSelectedFields<PgColumn>(fields);
		for (const f of fieldsList) {
			if (
				is(f.field, Column)
				&& getTableName(f.field.table)
					!== (is(table, Subquery)
						? table._.alias
						: is(table, PgViewBase)
						? table[ViewBaseConfig].name
						: is(table, SQL)
						? undefined
						: getTableName(table))
				&& !((table) =>
					joins?.some(({ alias }) =>
						alias === (table[Table.Symbol.IsAlias] ? getTableName(table) : table[Table.Symbol.BaseName])
					))(f.field.table)
			) {
				const tableName = getTableName(f.field.table);
				throw new Error(
					`Your "${
						f.path.join('->')
					}" field references a column "${tableName}"."${f.field.name}", but the table "${tableName}" is not part of the query! Did you forget to join it?`,
				);
			}
		}

		const isSingleTable = !joins || joins.length === 0;

		const withSql = this.buildWithCTE(withList);

		let distinctSql: SQL | undefined;
		if (distinct) {
			distinctSql = distinct === true ? sql` distinct` : sql` distinct on (${sql.join(distinct.on, sql`, `)})`;
		}

		const selection = this.buildSelection(fieldsList, { isSingleTable });

View on GitHub (pinned to b7862528fd)

Solutions

Add the missing join for the named table: .leftJoin(table, eq(...)).
Verify the alias used in joins matches getTableName of the referenced column's table.
If selecting only from one table, make sure the field's column actually belongs to that table singleton.
Ensure you imported a single shared table definition rather than re-declaring it in two files.

Example fix

// before — cities selected but never joined
db.select({ id: users.id, city: cities.name }).from(users);
// Your "city->..." field references a column "cities"."name", but the table "cities" is not part of the query!

// after — join the referenced table
db
  .select({ id: users.id, city: cities.name })
  .from(users)
  .leftJoin(cities, eq(users.cityId, cities.id));

Defensive patterns

Strategy: validation

Validate before calling

import { getTableName, is } from 'drizzle-orm';
import { Column } from 'drizzle-orm';

function assertFieldsCovered(
  fields: { field: any; path: string[] }[],
  fromTable: any,
  joinAliases: string[],
): void {
  const fromName = getTableName(fromTable);
  for (const f of fields) {
    if (is(f.field, Column)) {
      const t = getTableName(f.field.table);
      if (t !== fromName && !joinAliases.includes(t)) {
        throw new Error(`Field ${f.path.join('->')} needs table ${t} joined`);
      }
    }
  }
}

// call before/while building the select to fail fast with a clearer message

Type guard

import { is, getTableName } from 'drizzle-orm';
import { Column } from 'drizzle-orm';

function allSelectedFieldsJoined(
  fields: { field: any }[],
  fromTable: any,
  joins: { alias: string }[] | undefined,
): boolean {
  const allowed = new Set<string>([getTableName(fromTable)]);
  for (const j of joins ?? []) allowed.add(j.alias);
  return fields.every((f) => !is(f.field, Column) || allowed.has(getTableName(f.field.table)));
}

Prevention

Whenever you select a field from a related table, add the matching join in the same edit.
Reuse a single shared table definition across files to avoid duplicate singletons that confuse the alias check.
Review select field lists during code review for orphaned cross-table references.

When it happens

Trigger: Calling db.select({ ... }) (or the relational query API) where a selected field references a column from a table that is not the FROM table and is not present in the joins array. Constructing the select throws before any SQL is sent to the DB.

Common situations: Selecting fields from a related table and forgetting the .leftJoin(...)/.innerJoin(...) for it; renaming a table so an existing join alias no longer matches; using a column from the wrong table instance (two different table singletons with the same name).

Related errors

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