n8n-io/n8n · error · TypeORMError

Referenced column ${joinColumn.referencedColumnName} was not

Error message

Referenced column ${joinColumn.referencedColumnName} was not found in entity ${relation.inverseEntityMetadata.name}

What it means

For @ManyToOne / @OneToOne relations, `RelationJoinColumnBuilder` resolves each `@JoinColumn({ referencedColumnName })` against `relation.inverseEntityMetadata.ownColumns`. If the named column is not a directly-declared column on the inverse entity, TypeORM cannot build the foreign key and throws. The code comment notes it does not search inside other relations.

Source

Thrown at packages/@n8n/typeorm/src/metadata-builder/RelationJoinColumnBuilder.ts:133

	): ColumnMetadata[] {
		const hasAnyReferencedColumnName = joinColumns.find(
			(joinColumnArgs) => !!joinColumnArgs.referencedColumnName,
		);
		const manyToOneWithoutJoinColumn = joinColumns.length === 0 && relation.isManyToOne;
		const hasJoinColumnWithoutAnyReferencedColumnName =
			joinColumns.length > 0 && !hasAnyReferencedColumnName;

		if (manyToOneWithoutJoinColumn || hasJoinColumnWithoutAnyReferencedColumnName) {
			// covers case3 and case1
			return relation.inverseEntityMetadata.primaryColumns;
		} else {
			// cases with referenced columns defined
			return joinColumns.map((joinColumn) => {
				const referencedColumn = relation.inverseEntityMetadata.ownColumns.find(
					(column) => column.propertyName === joinColumn.referencedColumnName,
				); // todo: can we also search in relations?
				if (!referencedColumn)
					throw new TypeORMError(
						`Referenced column ${joinColumn.referencedColumnName} was not found in entity ${relation.inverseEntityMetadata.name}`,
					);

				return referencedColumn;
			});
		}
	}

	/**
	 * Collects columns from the given join column args.
	 */
	private collectColumns(
		joinColumns: JoinColumnMetadataArgs[],
		relation: RelationMetadata,
		referencedColumns: ColumnMetadata[],
	): ColumnMetadata[] {
		return referencedColumns.map((referencedColumn) => {
			// in the case if relation has join column with only name set we need this check

View on GitHub (pinned to 5ac6606e81)

Solutions

Ensure `referencedColumnName` is a real top-level column on the inverse entity (and is unique — FK targets must be unique/primary).
If the target column lives in an @Embedded, move it onto the entity directly so it appears in `ownColumns`.
Drop `referencedColumnName` to let TypeORM reference the inverse entity's primary key automatically.

Example fix

// before
@ManyToOne(() => User)
@JoinColumn({ referencedColumnName: 'email' })
author: User;  // User has no `email` column

// after — reference a real unique column (or omit it)
@ManyToOne(() => User)
@JoinColumn({ referencedColumnName: 'id' })
author: User;

Defensive patterns

Strategy: validation

Validate before calling

for (const m of dataSource.entityMetadatas) {
  for (const r of m.relations) {
    if (!r.joinColumns?.length) continue;
    const invOwn = r.inverseEntityMetadata.ownColumns.map(c => c.propertyName);
    for (const jc of r.joinColumns) {
      if (jc.referencedColumnName && !invOwn.includes(jc.referencedColumnName)) {
        throw new Error(`${m.name}#${r.propertyName}: referencedColumnName ${jc.referencedColumnName} not on ${r.inverseEntityMetadata.name}`);
      }
    }
  }
}

Try / catch

try { await dataSource.initialize(); } catch (e) { if (e instanceof TypeORMError && /Referenced column.*was not found/) { /* inspect @JoinColumn referencedColumnName vs inverse entity */ } throw e; }

Prevention

Point `referencedColumnName` at a unique/primary column directly declared on the inverse entity.
Avoid embedding the target column inside an @Embedded; promote it if you must reference it.
Omit `referencedColumnName` when you mean the inverse entity's PK.

When it happens

Trigger: Writing `@ManyToOne(() => User) @JoinColumn({ referencedColumnName: 'email' })` when `User` has no top-level `email` column (e.g. email lives in an embedded profile, or the column is named `emailAddress`).

Common situations: Referencing a unique column that is actually defined on a subclass or embedded entity. Renaming the inverse column and forgetting the @JoinColumn. Typing the referencedColumnName.

Related errors

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/8fbd248fb5360740. Report an issue: GitHub.