drizzle-team/drizzle-orm · error · Error

arrayOverlaps requires at least one value

Error message

arrayOverlaps requires at least one value

What it means

Thrown by arrayOverlaps() when the values argument is an empty Array. arrayOverlaps emits the '&&' (array-overlap) operator, which is meaningless with no elements to overlap, so drizzle rejects it up front at conditions.ts:732-733.

Source

Thrown at drizzle-orm/src/sql/expressions/conditions.ts:733

export function arrayOverlaps<T>(
	column: SQL.Aliased<T>,
	values: (T | Placeholder) | SQLWrapper,
): SQL;
export function arrayOverlaps<TColumn extends Column>(
	column: TColumn,
	values: (GetColumnData<TColumn, 'raw'> | Placeholder) | SQLWrapper,
): SQL;
export function arrayOverlaps<T extends SQLWrapper>(
	column: Exclude<T, SQL.Aliased | Column>,
	values: (unknown | Placeholder)[] | SQLWrapper,
): SQL;
export function arrayOverlaps(
	column: SQLWrapper,
	values: (unknown | Placeholder)[] | SQLWrapper,
): SQL {
	if (Array.isArray(values)) {
		if (values.length === 0) {
			throw new Error('arrayOverlaps requires at least one value');
		}
		const array = sql`${bindIfParam(values, column)}`;
		return sql`${column} && ${array}`;
	}

	return sql`${column} && ${bindIfParam(values, column)}`;
}

View on GitHub (pinned to b7862528fd)

Solutions

1. Skip the overlaps predicate when the candidate array is empty (no overlap is then the correct result anyway).
2. Validate the array length at the service layer before reaching the query builder.
3. Log and bail early if the filter source unexpectedly returned [].

Example fix

// before
.where(arrayOverlaps(posts.tags, tags)) // throws if tags === []

// after
const q = db.select().from(posts);
if (tags.length) q.where(arrayOverlaps(posts.tags, tags));

function safeArrayOverlaps(column, values) {
  if (Array.isArray(values) && values.length === 0) return undefined;
  return arrayOverlaps(column, values);
}

const isNonEmptyArray = (v): v is unknown[] => Array.isArray(v) && v.length > 0;

When it happens

Trigger: Calling arrayOverlaps(column, []) or arrayOverlaps(column, computedArray) where computedArray.length === 0. Non-array arguments (SQLWrapper/Placeholder) bypass the check.

Common situations: A 'matches any of' tag filter built from an empty UI selection; a recommended-tags list that came back empty from an API; passing an empty array constant by accident when refactoring.

Related errors

• arrayContains requires at least one value
• arrayContained requires at least one value
• values() must be called with at least one value
• Cannot pass undefined values to any set operator
• You have an empty array for "${name}" enum values

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