Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Prisma fails with prepared statement s0 already exists behind a pooler

ErrorError: undefined: Database error

Short answer

This error appears when Prisma talks to PostgreSQL through a transaction pooler such as PgBouncer. Prisma Migrate needs a direct connection, and Prisma Client needs the pooler flagged correctly. Point migrations at the direct URL, and for PgBouncer older than 1.21 add pgbouncer=true to the pooled URL.

  • Applies to Prisma ORM 6 and 7, PgBouncer 1.21+, PostgreSQL 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check the port and host of the URL that fails. Pooled URLs usually use a different port (Prisma's docs list 6543 for the Supabase transaction pooler) than the direct database port 5432.

    echo "$DATABASE_URL" | sed -E 's#(://[^:]+:)[^@]+@#\1***@#'
    echo "${DIRECT_URL:-no DIRECT_URL set}" | sed -E 's#(://[^:]+:)[^@]+@#\1***@#'
  2. 2Match what you see, then jump to its fix

    1. 1The error shows up on prisma migrate dev, migrate deploy or db push, and DATABASE_URL points at the poolerprisma migrate or db push runs through the poolerFix
    2. 2Prisma Client queries fail intermittently once traffic runs through PgBouncerPgBouncer cannot handle Prisma's prepared statementsFix
    3. 3The pooled URL uses the transaction-mode port (6543 on Supabase) and has no pgbouncer parameterPrisma Client runs through a Supavisor-style pooler without the flagFix

What does the error look like?

  • Error: undefined: Database error
  • Error querying the database: db error: ERROR: prepared statement "s0" already exists

Cause 1 of 3

prisma migrate or db push runs through the pooler

1Check

Prisma Migrate uses transactions and expects one stable connection, which a transaction-mode pooler does not give it. Check which URL the CLI reads.

grep -n -A3 "datasource" prisma.config.ts prisma/schema.prisma

2Fix

Give the CLI the direct connection string. In Prisma ORM 7 set datasource.url in prisma.config.ts to a DIRECT_URL variable, and keep the pooled URL for the client only.

// prisma.config.ts
import "dotenv/config";
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  datasource: { url: env("DIRECT_URL") },
});

3Verify

The migration now runs against the direct database.

npx prisma migrate deploy

Confirmed by prisma.io

Did this fix it?

Cause 2 of 3

PgBouncer cannot handle Prisma's prepared statements

1Check

In PgBouncer, a max_prepared_statements value above 0 is what lets it work with Prisma's prepared statements. Look at its configuration.

grep -n "max_prepared_statements" /etc/pgbouncer/pgbouncer.ini

2Fix

Set max_prepared_statements to a value greater than 0 so PgBouncer can use Prisma's prepared statements. On PgBouncer 1.21 or later, do not add pgbouncer=true; on older versions add it to the pooled URL.

; pgbouncer.ini
max_prepared_statements = 100

# PgBouncer older than 1.21 only
DATABASE_URL="postgres://USER:PASSWORD@HOST:6432/DATABASE?pgbouncer=true"

3Verify

Restart PgBouncer, then run the Prisma command or the request that failed again.

npx prisma migrate status

Confirmed by prisma.io

Did this fix it?

Cause 3 of 3

Prisma Client runs through a Supavisor-style pooler without the flag

1Check

Supavisor behaves like PgBouncer in transaction mode. Check whether the pooled connection string carries the parameter.

echo "$DATABASE_URL" | grep -c pgbouncer=true

2Fix

Add ?pgbouncer=true to the pooled string used by Prisma Client, and keep the direct URL for the CLI. Other poolers can use it when they have the same limits as PgBouncer.

DATABASE_URL="postgres://USER:PASSWORD@HOST:6543/DATABASE?pgbouncer=true"
DIRECT_URL="postgres://USER:PASSWORD@HOST:5432/DATABASE"

3Verify

Restart the app and call the route that failed twice in a row.

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/api/health

Confirmed by prisma.io

Did this fix it?

How do I stop it coming back?

  • Keep two variables in every environment: a pooled URL for the running app and a direct URL for the CLI.
  • Run migrations from the deploy step, not from the app's start script, so they never share the pooled path.
  • Read the pooler's version and mode when you adopt it, because the pgbouncer=true advice depends on the PgBouncer version.

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?

Related fixes

Next step

Want this handled for good?

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