Maaz Zindani

Loading the index…

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

Prisma Client fails with Invalid prisma.user.findUnique() invocation

ErrorCan't reach database server at `{database_host}`:`{database_port}`

Short answer

The first line, Invalid prisma.user.findUnique() invocation, only says which call failed. The reason is in the lines under it, usually with a code such as P1001, P2021, P2022 or P2025. Find the code, then fix the connection, apply the missing migrations, or change the query.

  • Applies to Prisma ORM 7, Node.js 22, PostgreSQL 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Catch the error and print its code and message. The code decides which cause below applies; the wrapper line says nothing about it.

    import { Prisma } from "../generated/prisma/client"; // the path your generator output uses
    try {
      await prisma.user.findUnique({ where: { email: "a@example.com" } });
    } catch (e) {
      if (e instanceof Prisma.PrismaClientKnownRequestError) console.error(e.code, e.message);
      else console.error(e.name, e.message);
    }
  2. 2Match what you see, then jump to its fix

    1. 1Can't reach database server at host:portThe database server cannot be reached (P1001)Fix
    2. 2The table `public.User` does not exist in the current databaseThe tables or columns are not in this database (P2021 or P2022)Fix
    3. 3PrismaClientKnownRequestError after a call to findUniqueOrThrow()findUniqueOrThrow found no recordFix
    4. 4PrismaClientValidationError naming the where argumentThe where filter is not a unique fieldFix

What does the error look like?

  • Can't reach database server at `{database_host}`:`{database_port}`
  • The table `{table}` does not exist in the current database.
  • The column `{column}` does not exist in the current database.
  • PrismaClientKnownRequestError

Cause 1 of 4

The database server cannot be reached (P1001)

1Check

P1001 is reported when Prisma cannot connect to the host and port in your connection string. Read the host and port in the message and compare them with DATABASE_URL, then check that the database is actually running there.

echo "$DATABASE_URL" | sed -E 's#//[^@]*@#//***@#'
node -e "require('net').connect(5432, 'localhost').on('connect', () => { console.log('open'); process.exit(0) }).on('error', (e) => { console.log(e.message); process.exit(1) })"

2Fix

Start the database, or correct the host, port and credentials in DATABASE_URL for the environment the app runs in.

# .env
DATABASE_URL="postgresql://app:secret@db-host.example.com:5432/appdb"

3Verify

Run the first-step script again. The query should return a user or null.

node check.mjs

Confirmed by prisma.io

Did this fix it?

Cause 2 of 4

The tables or columns are not in this database (P2021 or P2022)

1Check

The message names the missing table or column. This happens when the schema was never migrated into this database, for example a fresh production database or a new Docker volume.

ls prisma/migrations

2Fix

Apply the committed migrations. migrate deploy is the command for non-development environments, and it does not create new migrations. Since Prisma 7, migrate dev no longer runs prisma generate for you, so run it as well after schema changes.

npx prisma migrate deploy
npx prisma generate

3Verify

Run the query again; the code in the error should be gone.

node check.mjs

Confirmed by prisma.io

Did this fix it?

Cause 3 of 4

findUniqueOrThrow found no record

1Check

findUnique returns null when nothing matches, but findUniqueOrThrow throws a PrismaClientKnownRequestError in that case. Search the code for the Throw variant on the failing line.

grep -rn "findUniqueOrThrow" src/

2Fix

Use findUnique and handle null yourself, or catch the error where a missing record is a normal outcome.

const user = await prisma.user.findUnique({ where: { id } });
if (!user) return res.status(404).json({ error: "User not found" });

3Verify

Request an id that does not exist and confirm you get a 404 instead of a thrown error.

curl -i http://localhost:3000/users/does-not-exist

Confirmed by prisma.io

Did this fix it?

Cause 4 of 4

The where filter is not a unique field

1Check

The where input of findUnique selects a record by its id or a unique attribute. A field that is not marked @id or @unique in schema.prisma fails query validation.

grep -n -B2 -A8 "model User" prisma/schema.prisma

2Fix

Add @unique to the field if it is truly unique, then migrate. If it is not unique, use findFirst.

const user = await prisma.user.findFirst({ where: { name: "Sam" } });

3Verify

Run the call again and confirm there is no validation error.

node check.mjs

Confirmed by prisma.io

Did this fix it?

How do I stop it coming back?

  • Run prisma migrate deploy in the release step, before the app starts, for every environment.
  • Keep one DATABASE_URL per environment and print its host (not the password) at start-up.
  • Use findUniqueOrThrow only where a missing row is a real error.

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.