Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Prisma in NestJS runs out of pooled connections and queries time out

ErrorP2024

Short 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.

  • Applies to Prisma 6, Prisma 7, NestJS 11, PostgreSQL 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/
  2. 2Match what you see, then jump to its fix

    1. 1Several matches from the first-step grepMore than one PrismaClient instanceFix
    2. 2P2024 under load, not on a single requestPool is too small, or the timeout too short, for the loadFix
    3. 3Errors right after traffic bursts, with $disconnect in a request path$disconnect() is called after every requestFix

What does the error look like?

  • P2024
  • Queries 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 -l

Confirmed by docs.nestjs.com

Did this fix it?

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/ .env

2Fix

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/health

Confirmed by prisma.io

Did this fix it?

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

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.