OUT-3675 | PrismaClientInitializationError

[arpandhakal]

Changes

The setup. This app runs on Vercel and talks to a Neon Postgres database through Prisma. Vercel doesn't run "one server", it spins up many small server instances (lambdas) on demand, and each one keeps its own pool of database connections open.

The history. Back in May 2024, someone hit a database timeout and added a "hacky" workaround: a custom env var (POSTGRES_PRISMA_URL_HIGHER_CONNECTION_LIMIT) that lets us tack a connection_limit setting onto the database URL. Originally suggested at 20. Over time, it got bumped up to 100 , probably under the
(reasonable-sounding but wrong) assumption that "more connections = fewer timeouts."

Why that backfired. The database itself can only hold so many connections open at once. With connection_limit=100, every Vercel lambda thinks it's allowed to grab up to 100 connections. A handful of busy lambdas easily blows past the database's actual ceiling. When that happens, new queries just sit there waiting
for a slot. After 10 seconds, Prisma gives up and throws an error, and that's what Sentry was catching: ~30 of them per issue over two weeks, all the same root cause.

Why "fewer is better" works. A single request in this app only needs 1–2 connections at a time. So 5 is plenty. With each lambda capped at 5, even with lots of lambdas running, the total stays well under what the database can comfortably handle. No more waiting, no more timeouts.

The fix. Change one number in one env var in Vercel:

▎ &connection_limit=100 → &connection_limit=5&pool_timeout=20

[linear-code]

OUT-3675

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
client-profile-manager	Ready	Preview, Comment	May 13, 2026 11:29am

[greptile-apps]

Greptile Summary

This PR fixes recurring PrismaClientInitializationError timeouts caused by connection pool exhaustion on Vercel serverless. The root cause was connection_limit=100 — each lambda claiming up to 100 connections — quickly overwhelming the Neon Postgres ceiling across concurrent instances.

• Connection limit reduced: connection_limit dropped from 100 → 5, which is sufficient for this app's 1–2 connections-per-request workload and keeps the aggregate across all lambdas well within database capacity.
• Pool timeout added: pool_timeout=20 gives each lambda a 20-second window to acquire a free connection before erroring, providing headroom during brief traffic spikes.
• Documentation updated: prisma/schema.prisma comment now explains the serverless multiplier risk with a link to Prisma docs; .env.example exposes the new recommended value for local setup.

Confidence Score: 4/5

Safe to merge — the connection pool reduction is well-reasoned and addresses a documented production issue; only concern is the now-misleading env var name.

The configuration change itself is correct and clearly explained. The only rough edge is that POSTGRES_PRISMA_URL_HIGHER_CONNECTION_LIMIT was named for a limit that no longer applies, which will confuse future developers reading the env file cold.

.env.example — the variable name POSTGRES_PRISMA_URL_HIGHER_CONNECTION_LIMIT is now a misnomer and worth renaming if the Vercel env var can be updated at the same time.

Important Files Changed

Filename	Overview
.env.example	Adds POSTGRES_PRISMA_URL_HIGHER_CONNECTION_LIMIT with connection_limit=5 and pool_timeout=20; variable name is now a misnomer after the limit was reduced
prisma/schema.prisma	Comment updated to explain serverless connection pool rationale with a link to Prisma docs; no schema or model changes
AGENTS.md	Whitespace-only changes: blank lines added after a few section headings for readability

Sequence Diagram

sequenceDiagram
    participant V as Vercel Lambda
    participant P as Prisma Client (pool: 5 conns)
    participant PB as pgBouncer (Neon)
    participant DB as Neon Postgres

    Note over V,DB: Before (connection_limit=100)
    V->>P: Query
    P->>PB: Open up to 100 connections
    PB-->>P: DB ceiling exceeded → timeout after 10s
    P-->>V: PrismaClientInitializationError

    Note over V,DB: After (connection_limit=5, pool_timeout=20)
    V->>P: Query
    P->>PB: Open up to 5 connections
    PB->>DB: Forward query (within capacity)
    DB-->>PB: Result
    PB-->>P: Result
    P-->>V: Success

Loading

_{Reviews (1): Last reviewed commit: "fix(OUT-3675): updated documentation" | Re-trigger Greptile}

[greptile-apps]

Misleading variable name after the fix

The env var POSTGRES_PRISMA_URL_HIGHER_CONNECTION_LIMIT was originally named to describe bumping the limit up, but this PR intentionally drops it to 5 — making the name now actively misleading for any developer who reads it fresh. A name like POSTGRES_PRISMA_URL_POOL_PARAMS or POSTGRES_PRISMA_URL_WITH_POOL would be accurate under both the old and new values.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[priosshrsth]

@arpandhakal Not the fault of this PR, but the current env flow doesn;t sit good with me. It seems easy to break and do mistake with it like with VERCEL_URL problems we have across all the repos.

[priosshrsth]

This could easily be part of POSTGRES_PRISMA_URL imo. tbh I don't like this approach. What if env doesn not have url query in it? This makes our app more susceptiblt to break imo. wdyt?

[priosshrsth]

lgtm