Prisma in NestJS runs out of pooled connections and queries time out
P2024Short answer
Prisma throws P2024 when a queued query cannot get a connection before the pool timeout, 10 seconds by default. In a NestJS app the cause is usually more than one PrismaClient (each has its own pool), a pool too small for the load, or work that holds connections too long. Share one client and size the pool.
Fix it fast
1Find out which cause you have
Count how many places create a PrismaClient. More than one means more than one pool.
grep -rn "new PrismaClient" src/2Match what you see, then jump to its fix
What does the error look like?
P2024Queries fail after waiting for a free connection from the pool
Cause 1 of 3
More than one PrismaClient instance
1Check
Prisma creates a new pool with each new instance, so repeated instantiation exhausts database connections. Docs advise one instance across the app.
grep -rn "new PrismaClient\|extends PrismaClient" src/2Fix
Make PrismaService a single provider in one module that exports it, and inject it everywhere.
@Module({ providers: [PrismaService], exports: [PrismaService] })
export class PrismaModule {}3Verify
Only one match for the grep, then repeat the load that failed.
grep -rn "new PrismaClient" src/ | wc -lConfirmed by docs.nestjs.com
Cause 2 of 3
Pool is too small, or the timeout too short, for the load
1Check
On Prisma 6, the pool defaults to physical CPUs x 2 + 1 connections with a 10 second pool_timeout. On Prisma 7 the settings come from the driver adapter (for pg, max and connectionTimeoutMillis).
grep -rn "connection_limit\|pool_timeout\|PrismaPg" src/ .env2Fix
Prisma 6: set the limits in the connection URL. Prisma 7: pass them to the adapter. Keep the total across all app instances below the database limit.
# Prisma 6 (.env)
DATABASE_URL="postgresql://user:pass@localhost:5432/mydb?connection_limit=20&pool_timeout=20"
// Prisma 7
new PrismaPg({ connectionString: process.env.DATABASE_URL, max: 20, connectionTimeoutMillis: 20_000 });3Verify
Run the same load again and check the error stays away.
npx autocannon -c 50 -d 30 http://localhost:3000/healthConfirmed by prisma.io
Cause 3 of 3
$disconnect() is called after every request
1Check
The docs say it does not make sense to disconnect after each request, since reconnecting slows the app and closes all pooled connections.
grep -rn "\$disconnect" src/2Fix
Call it only on shutdown, in onModuleDestroy, with shutdown hooks enabled.
async onModuleDestroy() { await this.$disconnect(); }
// main.ts
app.enableShutdownHooks();3Verify
Confirm the only $disconnect call is in onModuleDestroy.
grep -rn "\$disconnect" src/Confirmed by prisma.io
How do I stop it coming back?
- Keep a single PrismaClient per app process.
- Work out pool size as database max connections divided by app instances.
- Use an external pooler such as PgBouncer when you run many instances or serverless functions.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Databases
Prisma says it can't reach the database server, but the database is up
Please make sure your database server is running at `localhost`:`5432`.
P1001 is Prisma's catch-all for any failed connection, even a wrong password, so do not trust the label.
4 causes, each with a fixBack end
PostgreSQL error: bind message has N parameter formats but 0 parameters
QueryFailedError: bind message has N parameter formats but 0 parameters
One query is carrying more bound values than the Postgres protocol can describe.
2 causes, each with a fixBack end
TypeORM sync fails when a new column is NOT NULL on an existing table
QueryFailedError: column "price" contains null values
TypeORM columns are NOT NULL by default.
3 causes, each with a fixBack end
TypeORM migration:generate finds no changes to put in the migration
typeorm migration:generate finds no changes in the database schema, writes no file and exits with code 1
migration:generate compares the entities your DataSource loads with the real database, and writes only the difference.
4 causes, each with a fixBack end
TypeORM connects but creates no tables or columns
A new column is missing, with no error at startup
TypeORM does not create tables by itself.
3 causes, each with a fixBack end
TypeScript cannot find module '@nestjs/core' or its type declarations
error TS2307: Cannot find module '@nestjs/common' or its corresponding type declarations.
TS2307 means TypeScript searched node_modules and found neither the package nor its types.
3 causes, each with a fix