{"id":"e66931b7bd6e9bc1","repo":"drizzle-team/drizzle-orm","slug":"cannot-execute-a-query-on-a-query-builder-please-e66931","errorCode":null,"errorMessage":"Cannot execute a query on a query builder. Please use a database instance instead.","messagePattern":"Cannot execute a query on a query builder\\. Please use a database instance instead\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"drizzle-orm/src/pg-core/query-builders/select.ts","lineNumber":1081,"sourceCode":"\tTSelectedFields = BuildSubquerySelection<TSelection, TNullabilityMap>,\n> extends PgSelectQueryBuilderBase<\n\tPgSelectHKT,\n\tTTableName,\n\tTSelection,\n\tTSelectMode,\n\tTNullabilityMap,\n\tTDynamic,\n\tTExcludedMethods,\n\tTResult,\n\tTSelectedFields\n> implements RunnableQuery<TResult, 'pg'>, SQLWrapper {\n\tstatic override readonly [entityKind]: string = 'PgSelect';\n\n\t/** @internal */\n\t_prepare(name?: string): PgSelectPrepare<this> {\n\t\tconst { session, config, dialect, joinsNotNullableMap, authToken, cacheConfig, usedTables } = this;\n\t\tif (!session) {\n\t\t\tthrow new Error('Cannot execute a query on a query builder. Please use a database instance instead.');\n\t\t}\n\n\t\tconst { fields } = config;\n\n\t\treturn tracer.startActiveSpan('drizzle.prepareQuery', () => {\n\t\t\tconst fieldsList = orderSelectedFields<PgColumn>(fields);\n\t\t\tconst query = session.prepareQuery<\n\t\t\t\tPreparedQueryConfig & { execute: TResult }\n\t\t\t>(dialect.sqlToQuery(this.getSQL()), fieldsList, name, true, undefined, {\n\t\t\t\ttype: 'select',\n\t\t\t\ttables: [...usedTables],\n\t\t\t}, cacheConfig);\n\t\t\tquery.joinsNotNullableMap = joinsNotNullableMap;\n\n\t\t\treturn query.setToken(authToken);\n\t\t});\n\t}\n","sourceCodeStart":1063,"sourceCodeEnd":1099,"githubUrl":"https://github.com/drizzle-team/drizzle-orm/blob/b7862528fd8fc39bc2653a6c18dad7c1f4e68d10/drizzle-orm/src/pg-core/query-builders/select.ts#L1063-L1099","documentation":"PgSelectBase._prepare (select.ts:1080) throws when the query builder has no session, because executing requires a database connection to prepare the statement. A select built from a standalone QueryBuilder (new QueryBuilder()) or detached from a db instance carries no session and therefore cannot run.","triggerScenarios":"Constructing a query with `new QueryBuilder()` and then calling .execute()/.prepare(); exporting a select builder without binding it to a db; passing a builder to a function that calls execute on it without a db.","commonSituations":"Trying to reuse query-construction helpers across modules by instantiating QueryBuilder directly; migrating from a raw SQL flow and forgetting to use the db instance; calling execute on a select returned from a test stub.","solutions":["Build queries from a real db instance (drizzle(...)) so the session is attached: db.select().from(t).","Pass the db into helper functions rather than constructing a standalone QueryBuilder.","If you only need the SQL string, use qb.toSQL() or build the SQL without calling execute."],"exampleFix":"// before\nconst qb = new QueryBuilder();\nawait qb.select().from(users).execute(); // no session -> error\n\n// after\nconst db = drizzle(client);\nawait db.select().from(users).execute();","handlingStrategy":"validation","validationCode":"// Ensure queries are built from a db instance, never a bare QueryBuilder.\nfunction assertDb<T extends { session: unknown }>(db: T): asserts db is T & { session: object } {\n  if (!db || !(db as any).session) {\n    throw new Error('A db instance with a session is required to execute queries');\n  }\n}\nassertDb(db);\nawait db.select().from(users).execute();","typeGuard":"function isBindableDb(db: unknown): db is { select: Function; execute: Function } {\n  return db != null && typeof (db as any).select === 'function'\n    && typeof (db as any).execute === 'function';\n}","tryCatchPattern":null,"preventionTips":["Always build queries via drizzle(client).select().","Inject the db into helpers instead of constructing QueryBuilder directly.","Use toSQL() if you only need the SQL string."],"tags":["select","session","query-builder","usage"],"analyzedSha":"b7862528fd8fc39bc2653a6c18dad7c1f4e68d10","analyzedAt":"2026-08-03T18:11:14.318Z","schemaVersion":2}