n8n-io/n8n · error · EntityNotFoundError

Could not find any entity of type "${target}" matching: ${cr

Error message

Could not find any entity of type "${target}" matching: ${criteria}

What it means

Thrown as EntityNotFoundError from getOneOrFail() when the underlying getOne() returns null. It reports the main alias target and the bound parameters so the caller can see what was searched for. Unlike getOne() (which resolves null), this variant rejects, enforcing that an entity must exist.

Source

Thrown at packages/@n8n/typeorm/src/query-builder/SelectQueryBuilder.ts:1593

						actualVersion,
					);
			}
		}

		if (result === undefined) {
			return null;
		}
		return result;
	}

	/**
	 * Gets the first entity returned by execution of generated query builder sql or rejects the returned promise on error.
	 */
	async getOneOrFail(): Promise<Entity> {
		const entity = await this.getOne();

		if (!entity) {
			throw new EntityNotFoundError(
				this.expressionMap.mainAlias!.target,
				this.expressionMap.parameters,
			);
		}

		return entity;
	}

	/**
	 * Gets entities returned by execution of generated query builder sql.
	 */
	async getMany(): Promise<Entity[]> {
		if (this.expressionMap.lockMode === 'optimistic') throw new OptimisticLockCanNotBeUsedError();

		const results = await this.getRawAndEntities();
		return results.entities;
	}

View on GitHub (pinned to 5ac6606e81)

Solutions

If a missing row is a legitimate case, use getOne() and handle null instead of getOneOrFail().
If the row must exist, verify the id/tenant/filter before querying, and return a 404 with context to the caller.
Check scopes/soft-delete/global filters that may be hiding the row.

Example fix

// before
const user = await repo.createQueryBuilder().where({ id }).getOneOrFail();
// after
const user = await repo.createQueryBuilder().where({ id }).getOne();
if (!user) throw new NotFoundException(`user ${id} not found`);

Defensive patterns

Strategy: validation

Validate before calling

async function findOr404<T>(qb: SelectQueryBuilder<T>): Promise<T> {
  const entity = await qb.getOne();
  if (!entity) {
    const err = new Error(`entity not found`);
    (err as any).status = 404;
    throw err;
  }
  return entity;
}
// then: const u = await findOr404(repo.createQueryBuilder().where({ id }));

Type guard

function isEntityNotFoundError(e: unknown): boolean {
  return e instanceof Error && e.name === 'EntityNotFoundError';
}

Try / catch

try {
  return await qb.getOneOrFail();
} catch (e) {
  if (e?.name === 'EntityNotFoundError') throw new NotFoundException('resource not found');
  throw e;
}

Prevention

Prefer getOne() with explicit null checks when a missing row is a valid case.
Map EntityNotFoundError to an HTTP 404 at the controller boundary.
Check soft-delete/global filters and tenant scopes that may hide the row.

When it happens

Trigger: Calling `.getOneOrFail()` on a query whose WHERE matches zero rows: wrong id, soft-deleted row excluded by a global scope, filtered tenant, or a race where the row was deleted between select-for-update and getOne.

Common situations: Lookup-by-id endpoints that should 404; reference-data loads where a foreign key points at a missing row; tests against a freshly-migrated DB missing seed data; multi-tenant filters that silently exclude the row.

Related errors

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