drizzle-team/drizzle-orm · error · Error

Cannot execute a query on a query builder. Please use a data

Error message

Cannot execute a query on a query builder. Please use a database instance instead.

What it means

Thrown by SQLiteSelectBase._prepare (select.ts:913) when the select builder has no session attached. A select built via the standalone QueryBuilder (or otherwise detached from a db instance) cannot be executed because there is no driver connection to compile and run it against. You can still call .toSQL() on such a builder, but .run/.all/.get/.execute require a real db instance.

Source

Thrown at drizzle-orm/src/sqlite-core/query-builders/select.ts:913

> extends SQLiteSelectQueryBuilderBase<
	SQLiteSelectHKT,
	TTableName,
	TResultType,
	TRunResult,
	TSelection,
	TSelectMode,
	TNullabilityMap,
	TDynamic,
	TExcludedMethods,
	TResult,
	TSelectedFields
> implements RunnableQuery<TResult, 'sqlite'>, SQLWrapper {
	static override readonly [entityKind]: string = 'SQLiteSelect';

	/** @internal */
	_prepare(isOneTimeQuery = true): SQLiteSelectPrepare<this> {
		if (!this.session) {
			throw new Error('Cannot execute a query on a query builder. Please use a database instance instead.');
		}
		const fieldsList = orderSelectedFields<SQLiteColumn>(this.config.fields);
		const query = this.session[isOneTimeQuery ? 'prepareOneTimeQuery' : 'prepareQuery'](
			this.dialect.sqlToQuery(this.getSQL()),
			fieldsList,
			'all',
			true,
			undefined,
			{
				type: 'select',
				tables: [...this.usedTables],
			},
			this.cacheConfig,
		);
		query.joinsNotNullableMap = this.joinsNotNullableMap;
		return query as ReturnType<this['prepare']>;
	}

View on GitHub (pinned to b7862528fd)

Solutions

Build the query from a db instance: db.select()... so the session is attached.
If you only need the SQL text, call .toSQL() instead of an execute method.
Ensure the db/client is initialised (e.g. drizzle(...)) before constructing runnable queries.

Example fix

// before — QueryBuilder has no session
const qb = new QueryBuilder();
const rows = await qb.select().from(users).all(); // throws

// after — build from a db instance
const db = drizzle(client);
const rows = await db.select().from(users).all();

Defensive patterns

Strategy: type-guard

Validate before calling

function assertExecutable(builder) {
  if (!builder.session) {
    throw new Error('Builder has no db session; build from db.select() or use .toSQL()');
  }
}

Type guard

const isRunnable = (q): boolean =>
  q && typeof q === 'object' && '_prepare' in q && !!q.session;

Prevention

Always construct runnable queries from a db instance, never from new QueryBuilder().
Use .toSQL() when you only need the SQL string (e.g. in tests).
Initialise the drizzle db before importing modules that build queries at module load.

When it happens

Trigger: Creating a query via new QueryBuilder() (the class, not db.$queryRaw) and calling .all()/.execute(); passing a select built outside a db context into something that calls .execute(); calling prepare()/run() on a builder returned by a helper that stripped the session.

Common situations: Unit-testing query construction without a db; extracting a query into a function that returns the builder instead of running it; using the wrong import (QueryBuilder vs db.select); SSR/edge runtimes where the db was not initialised before the call.

Related errors

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