Prisma "binaryTargets" / musl Engine Mismatch on Alpine

Prisma Client ships a query engine compiled for a specific platform. When the engine was generated for glibc (Debian) but the container runs on musl (Alpine), the runtime cannot load it - a build/runtime platform mismatch, not a transient failure.

What this error means

Prisma works in one image but, on an Alpine-based stage, fails at runtime with "could not locate the Query Engine" for linux-musl-.... It is deterministic - the wrong engine binary was generated for the running libc.

prisma output

PrismaClientInitializationError: Unable to require(`.../libquery_engine-linux-musl-openssl-3.0.x.so.node`)
Prisma Client could not locate the Query Engine for runtime "linux-musl-openssl-3.0.x".

Common causes

Engine generated for the wrong libc

The default binaryTargets produced a glibc engine, but the deploy/runtime image is Alpine (musl). The required linux-musl-* engine was never generated.

Multi-stage build generated on a different base

A build stage on Debian runs prisma generate, then the artifact is copied into an Alpine runtime stage that needs a different engine.

OpenSSL version drift in the target image

The engine name encodes the OpenSSL version (e.g. openssl-3.0.x). An image with a different OpenSSL has no matching engine.

How to fix it

Declare the musl binary target

Add the native platform and the musl target so generation produces both engines.

schema.prisma

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

Generate on the same base as the runtime

Run prisma generate in a stage whose base image matches the runtime (Alpine for Alpine).
Or switch the runtime to a glibc base (e.g. node:20-slim) to match the default engine.
Verify the engine file present in the image matches the runtime platform name.

How to prevent it

Set binaryTargets to every platform you run on, including linux-musl-* for Alpine.
Generate Prisma Client on an image matching the runtime libc/OpenSSL.
Pin base images so the engine target stays stable.