Backend

Prisma query engine, OpenSSL, Alpine | 도커만 엔진이 없으면?

프리즈마 쿼리 엔진을 못 찾으면 SQL이 틀린 게 아니라 그 운영체제와 OpenSSL에 맞는 바이너리가 이미지 안에 없는 줄입니다. binaryTargets, 알파인 musl, 이미지 안 generate. Prisma, Docker, Next.js, 한국 1인 개발자 기준. 2026년 9월 프리즈마 제너레이터·스키마 문서.

by Lee발행: 2026-09-21

프리즈마 쿼리 엔진을 못 찾으면 SQL이 틀린 게 아니라, 그 운영체제와 OpenSSL에 맞는 바이너리가 이미지 안에 없는 줄입니다. 맥에서 generate한 클라이언트를 리눅스 컨테이너에 그대로 넣으면 납니다.

로컬 npx prisma studio는 되는데 도커 빌드만 Query Engine을 못 찾는 일, 알파인 이미지에서 한 번은 만납니다. 스키마를 고치기 전에 타깃부터 보세요.

binaryTargets에 배포 OS를 넣고, 이미지 안에서 prisma generate를 다시 하세요. 근거는 프리즈마 제너레이터 문서와 스키마 레퍼런스에 있습니다.

쿼리가 아니라 엔진 파일이다

클라이언트가 쿼리를 보내려면 플랫폼용 엔진 파일이 옆에 있어야 합니다. 맥에서 만든 libquery_engine-darwin-arm64.dylib.node는 알파인에서 못 엽니다. 에러가 찾는 런타임 이름을 그대로 읽으세요.

프리즈마 문서는 native가 지금 기계의 타깃을 자동으로 고른다고 적습니다. 로컬이 맥이면 native는 darwin이고, 배포가 데비안이면 그 파일이 없습니다. 그래서 로컬은 되고 컨테이너만 죽습니다.

TCP가 안 열린 P1001, 유니크 충돌 P2002와 자리가 다릅니다. 엔진 줄은 쿼리 전에 납니다. 연결은 P1001, 중복 키는 P2002를 보세요.

에러가 찾는 이름	실제 환경	넣을 타깃
darwin-arm64	맥 Apple Silicon	native로 충분
debian-openssl-3.0.x	공식 node 슬림, 우분투	native, debian-openssl-3.0.x
linux-musl-openssl-3.0.x	알파인 3.17+	native, linux-musl-openssl-3.0.x
rhel-openssl-3.0.x	아마존 리눅스, 일부 서버리스	native, rhel-openssl-3.0.x

메시지에 적힌 런타임을 복사하세요 | "generated for darwin-arm64, required debian-openssl-3.0.x"처럼 두 이름이 나옵니다. 앞은 빌드 기계, 뒤는 실행 기계입니다. 뒤에 적힌 이름을 binaryTargets에 넣습니다.

맥에서 만든 프리즈마 엔진이 리눅스 컨테이너에서 없는 개념 이미지 — 로컬 generate 결과물을 컨테이너에 복사하면 엔진 파일이 플랫폼과 어긋난다

binaryTargets에 배포 OS를 적는다

스키마 generator에 로컬과 배포를 같이 적습니다. native는 지금 기계용이고, 두 번째 값이 컨테이너용입니다. 저장한 뒤 반드시 generate를 다시 돌려야 파일이 내려옵니다.

알파인 3.17부터는 OpenSSL 3이라 linux-musl만 넣으면 안 맞고 linux-musl-openssl-3.0.x가 필요합니다. 데비안 계열 공식 node:20-bookworm-slim은 debian-openssl-3.0.x입니다.

타깃을 여러 개 넣으면 설치와 generate가 무거워집니다. 쓰는 배포 한두 개만 적으세요. 버셀 서버리스는 환경에 따라 rhel 계열이 나옵니다. 에러가 요구한 문자열을 그대로 쓰는 편이 안전합니다.

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

// 데비안 슬림 이미지라면
// binaryTargets = ["native", "debian-openssl-3.0.x"]

generate는 이미지 안에서 다시 한다

맥 node_modules/.prisma를 도커로 복사하면 엔진이 맥용입니다. npm ci 뒤에 컨테이너에서 npx prisma generate를 돌리세요. 멀티 스테이지여도 generate는 최종 런타임과 같은 libc 위에서 해야 합니다.

알파인에 openssl 라이브러리가 없으면 generate가 타깃을 잘못 고르거나 실행 때 로더가 실패합니다. apk add openssl을 이미지에 넣고, glibc가 필요하면 알파인 대신 데비안 슬림이 낫습니다.

모듈 이름 자체를 못 찾는 줄은 Cannot find module입니다. 엔진 줄은 패키지는 있는데 .so.node 파일이 없거나 못 읽는 쪽입니다. .dockerignore가 node_modules만 막고 generate를 빼먹으면 같은 증상이 납니다.

실수	결과	고칠 칸
맥 generate 결과 복사	darwin 엔진만 존재	이미지 안 generate
알파인 + musl 구타깃	OpenSSL 3 불일치	linux-musl-openssl-3.0.x
.prisma를 dockerignore	엔진 파일 없음	ignore 후 generate
번들러가 .so.node 누락	런타임 경로에 파일 없음	외부 패키지로 표시

Dockerfile에서 generate
FROM node:20-alpine AS deps
RUN apk add --no-cache openssl
WORKDIR /app
COPY package.json package-lock.json prisma ./
RUN npm ci
RUN npx prisma generate

FROM node:20-alpine
RUN apk add --no-cache openssl
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
CMD ["node", "server.js"]

도커 이미지 빌드 중 prisma generate를 실행하는 개념 이미지 — 엔진은 실행할 이미지와 같은 OS에서 generate해야 맞는다

OpenSSL 1.1과 3이 갈리는 자리

같은 리눅스라도 OpenSSL 메이저가 다르면 엔진 이름이 갈립니다. 옛 우분투는 1.1.x, 최근 데비안과 알파인 3.17+는 3.0.x입니다. 1.1용 파일을 3 위에 올리면 로더가 심볼을 못 찾습니다.

에러가 1.1을 요구하면 이미지가 옛 라이브러리를 쓰는 겁니다. 베이스 태그를 올리거나, 타깃을 3.0.x로 맞추고 generate를 다시 합니다. 둘 다 넣으면 용량만 늘고 한 시점에 쓰는 건 하나입니다.

한국에서 슈퍼베이스와 넥스트를 버셀에 올리는 구성은 컨테이너를 안 쓰는 경우가 많아 이 줄이 드뭅니다. 자체 도커나 깃허브 액션 셀프 호스트에서 알파인으로 빌드할 때 주로 납니다.

[ ] 에러가 요구한 런타임 이름을 그대로 복사했다
[ ] binaryTargets에 native와 배포 타깃을 적었다
[ ] 컨테이너 안에서 prisma generate를 돌렸다
[ ] 알파인이면 openssl 패키지와 musl OpenSSL 3 타깃을 맞췄다
[ ] 맥 node_modules를 런타임 이미지에 복사하지 않았다

실전에서 고르는 순서

메시지에 적힌 required 런타임을 스키마에 넣고 generate를 이미지 안에서 다시 합니다. 그래도 없으면 베이스 이미지의 libc와 OpenSSL을 에러 이름과 대조하세요. 연결 거절은 ECONNREFUSED입니다.

번들러가 엔진 파일을 삼키면 generate는 성공해도 런타임 경로에 파일이 없습니다. 넥스트는 서버 전용 패키지로 프리즈마를 외부 처리하는 설정이 있습니다. 클라이언트 번들에 넣지 마세요.

알파인에서 계속 막히면 데비안 슬림으로 베이스를 바꾸는 편이 빠를 때가 있습니다. 리눅스 표준 라이브러리와 암호 라이브러리 조합을 맞추는 시간보다 이미지가 조금 커지는 쪽이 운영이 단순합니다.

한국에서 슈퍼베이스 호스트만 쓰고 컨테이너를 안 띄우는 구성이면 이 줄을 잘 안 만납니다. 자체 서버나 액션에서 이미지를 쪼개 빌드할 때, 빌드 단계 기계와 실행 단계 기계가 다르다는 점만 기억하면 됩니다. 에러 문장에 적힌 두 이름을 복사해 표에 대조하는 일이 스키마를 되돌리는 일보다 짧습니다. 로컬에서 잘 되던 조회가 배포만 안 되면 테이블을 의심하기 쉬운데, 엔진 파일 줄은 조회 전에 이미 멈춘 상태입니다. 데이터베이스 주소를 고치기 전에 실행 환경이 어떤 운영체제인지, 빌드가 그 환경에서 엔진을 다시 만들었는지만 확인하면 됩니다. 테이블을 지우고 다시 만들어도 엔진 파일이 없으면 조회는 시작조차 하지 않습니다.