typeorm/typeorm · error · TypeORMError

Undefined value encountered in property '${alias}.${key}' of

Error message

Undefined value encountered in property '${alias}.${key}' of a where condition. Set 'invalidWhereValuesBehavior.undefined' to 'ignore' in connection options to skip properties with undefined values.

What it means

Thrown in buildWhere when a where value is strictly undefined and the connection option invalidWhereValuesBehavior.undefined is at its default 'throw'. TypeORM refuses to silently produce 'col = NULL' (which never matches) or skip the predicate; it makes the ambiguity explicit. Set the option to 'ignore' to drop such properties instead.

Source

Thrown at src/query-builder/SelectQueryBuilder.ts:4376

                    metadata.findColumnWithPropertyPathStrict(propertyPath)
                const embed =
                    metadata.findEmbeddedWithPropertyPath(propertyPath)
                const relation =
                    metadata.findRelationWithPropertyPath(propertyPath)

                if (!embed && !column && !relation) {
                    throw new EntityPropertyNotFoundError(
                        propertyPath,
                        metadata,
                    )
                }

                if (parameterValue === undefined) {
                    const undefinedBehavior =
                        this.dataSource.options.invalidWhereValuesBehavior
                            ?.undefined ?? "throw"
                    if (undefinedBehavior === "throw") {
                        throw new TypeORMError(
                            `Undefined value encountered in property '${alias}.${key}' of a where condition. ` +
                                `Set 'invalidWhereValuesBehavior.undefined' to 'ignore' in connection options to skip properties with undefined values.`,
                        )
                    }
                    continue
                }

                if (parameterValue === null) {
                    const nullBehavior =
                        this.dataSource.options.invalidWhereValuesBehavior
                            ?.null ?? "throw"
                    if (nullBehavior === "ignore") {
                        continue
                    } else if (nullBehavior === "throw") {
                        throw new TypeORMError(
                            `Null value encountered in property '${alias}.${key}' of a where condition. ` +
                                `To match with SQL NULL, the IsNull() operator must be used. ` +
                                `Set 'invalidWhereValuesBehavior.null' to 'ignore' or 'sql-null' in connection options to skip or handle null values.`,

View on GitHub (pinned to 04ff4daedc)

Solutions

Strip undefined values from the where object before calling find (e.g. JSON.parse(JSON.stringify(where)) or a compact utility).
Set invalidWhereValuesBehavior: { undefined: 'ignore' } in DataSource options if dropping is the desired behavior.
Default optional inputs to a concrete value or use FindOperator (IsNull, IsNull, etc.) explicitly.
Use a typed where builder that omits undefined keys.

Example fix

// before
const email = req.query.email // string | undefined
repo.find({ where: { email } })

// after
const where: FindOptionsWhere<User> = {}
if (typeof email === 'string') where.email = email
repo.find({ where })

Defensive patterns

Strategy: validation

Validate before calling

function stripUndefined<T extends object>(obj: T): T {
  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined)) as T
}
repo.find({ where: stripUndefined(rawWhere) })

Type guard

function hasNoUndefined(obj: Record<string, unknown>): boolean {
  return Object.values(obj).every(v => v !== undefined)
}

Prevention

Build where objects conditionally: only set keys with concrete values.
Set invalidWhereValuesBehavior: { undefined: 'ignore' } if dropping undefined is intended.
Treat optional HTTP params as absent rather than undefined in the where map.

When it happens

Trigger: Calling repo.find({ where: { email: maybeUndefined } }) where maybeUndefined is undefined at runtime; spreading an object that has optional keys not set; using a query-string value that was not provided. The default undefined behavior is 'throw'.

Common situations: Optional HTTP query params mapped directly into where; partial search forms; object spread that copies undefined; upgrading TypeORM to a version that introduced invalidWhereValuesBehavior (older versions silently included undefined).

Related errors

AI-assisted analysis of typeorm/typeorm@04ff4daedc (2026-08-03). Data as JSON: /data/errors/6ba2a67663e9e174.json. Report an issue: GitHub.