Maaz Zindani

Loading the index…

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

Prisma cannot load its query engine on the server

ErrorUnable to require(`node_modules/prisma/libquery_engine-debian-openssl-1.1.x.so.node`)

Short answer

Prisma Client ships a native query engine built for one OS and OpenSSL version. If you generate on one system and run on another, the file does not match. Add the runtime's target to binaryTargets in schema.prisma and run prisma generate again.

  • Applies to Prisma ORM 6, Node.js 22, Debian 12, Alpine 3.20
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find which OS the app really runs on. The name of the missing engine file also tells you which target was generated.

    cat /etc/os-release
  2. 2Match what you see, then jump to its fix

    1. 1The file name in the error ends in openssl-1.1.x but the server is Debian 12 or Ubuntu 22.04Generated for a different OpenSSL than the runtime hasFix
    2. 2The runtime image is Alpine and the engine file name contains debianBuilt on a glibc machine, run on AlpineFix

What does the error look like?

  • Unable to require(`node_modules/prisma/libquery_engine-debian-openssl-1.1.x.so.node`)

Cause 1 of 2

Generated for a different OpenSSL than the runtime has

1Check

Prisma's docs map Debian 12 and Ubuntu 22.04 to debian-openssl-3.0.x, and Debian 9 to 11 and Ubuntu 18.04 to 21.04 to debian-openssl-1.1.x.

grep -n "binaryTargets" prisma/schema.prisma
cat /etc/os-release

2Fix

List the default and the runtime target in the generator, then generate again.

generator client {
  provider      = "prisma-client-js"
  binaryTargets = ["native", "debian-openssl-3.0.x"]
}

# then
npx prisma generate

3Verify

Generate again and start the app on the target system.

npx prisma generate

Confirmed by prisma.io

Did this fix it?

Cause 2 of 2

Built on a glibc machine, run on Alpine

1Check

The docs list linux-musl-openssl-3.0.x for Alpine 3.17 and newer, which is a different build from the Debian one.

cat /etc/alpine-release
grep -n "FROM" Dockerfile

2Fix

Add the musl target for the Alpine version you use and regenerate.

generator client {
  provider      = "prisma-client-js"
  binaryTargets = ["native", "linux-musl-openssl-3.0.x"]
}

3Verify

Rebuild the image and run it.

npx prisma generate
docker build -t my-app .

Confirmed by prisma.io

Did this fix it?

How do I stop it coming back?

  • Set binaryTargets whenever the build machine and the runtime differ.
  • Run prisma generate inside the same image that runs the app when you can.
  • Do not upgrade the base image's OS version without re-checking the target name.

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

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

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