Backend

Prisma Query Engine, binaryTargets, 엔진 파일 | 프리뷰만 엔진을 못 찾으면?

Query Engine for runtime rhel-openssl-3.0.x는 프리뷰 번들 옆에 그 런타임 엔진 파일이 없을 때 납니다. 로그의 이름을 binaryTargets에 넣고 prisma generate를 빌드에서 다시 실행합니다. native만 만들면 맥 파일만 갑니다. P2028, P1001과는 문장이 다릅니다. Prisma, OpenSSL, 버셀, 한국 1인 개발. 2026년 10월 문서.

by Lee발행: 2026-10-06

프리뷰 로그만 쿼리 엔진을 못 찾는다면, 표와 연결이 죽은 게 아니라 그 런타임용 엔진 파일이 번들 옆에 없는 자리입니다. 로그에 적힌 런타임 이름을 타깃 목록에 넣고, 생성 명령을 빌드에서 다시 돌리세요.

맥에서는 조회가 초록인데 버셀 프리뷰의 첫 쿼리만 초기화 오류로 죽습니다. 로컬 기본 타깃은 지금 노트북 하나라, 맥에서 만든 클라이언트가 리눅스 엔진 파일을 안 가지고 갑니다.

스키마 문서의 기본 타깃은 현재 기계입니다. 설치 캐시가 생성을 건너뛰는 문구는 따로 있습니다. 트랜잭션 시간 초과, 호스트 접속 실패와는 문장이 다릅니다. 근거는 타깃 목록 문서입니다.

로그의 런타임 이름이 받을 파일이다

이 오류는 쿼리 엔진 바이너리를 쓰는 클라이언트에서 납니다. 생성기의 provider가 prisma-client-js이거나 engineType이 library일 때, 프리즈마는 운영체제마다 libquery_engine-*.so.node를 받습니다.

기본 binaryTargets는 native입니다. 맥에서 generate하면 맥용 파일만 생깁니다. 프리뷰 함수가 찾는 이름이 rhel-openssl-3.0.x이면, 그 문자열이 스키마에 있어야 빌드 머신이 그 파일을 받습니다. 이름을 추측해서 debian-openssl-3.0.x만 넣으면, 로그가 찾는 파일과 받은 파일이 여전히 다릅니다.

프리즈마 7의 기본 생성기 prisma-client는 쿼리 컴파일러를 쓰고, 이 바이너리 목록 칸이 없습니다. 그런데도 로그가 libquery_engine을 말하면, 실행 중인 import가 아직 옛 클라이언트입니다. 새 생성기로 옮긴 뒤에도 옛 출력 폴더를 불러오면 같은 줄이 남습니다.

한 줄로 가를 것 | 로그에 .so.node 파일 이름이 있으면 바이너리 엔진입니다. 그 이름의 가운데 토큰을 binaryTargets에 그대로 넣습니다.

형광등 아래 서버 랙이 길게 늘어선 통로 — 프리뷰가 찾는 엔진은 맥에서 받은 native 파일과 다른 빌드입니다

로그 이름과 넣을 타깃

스키마 문서의 리눅스 표에서, 로그에 찍힌 문자열과 같은 줄만 고릅니다. 배포가 레드햇 계열 OpenSSL 3이면 rhel-openssl-3.0.x입니다. 알파인 3.17 이후 x64는 linux-musl-openssl-3.0.x입니다. 우분투 22.04는 debian-openssl-3.0.x입니다.

로그의 런타임	binaryTargets에 넣을 값	자주 있는 곳
rhel-openssl-3.0.x	같은 문자열	버셀 노드, OpenSSL 3
debian-openssl-3.0.x	같은 문자열	우분투 22.04, 데비안 12
linux-musl-openssl-3.0.x	같은 문자열	알파인 3.17 이후
darwin, darwin-arm64	native로 충분할 때가 많음	맥 로컬

로컬 개발을 유지하려면 native를 빼지 않습니다. 배열은 native와 로그의 이름, 두 칸이면 됩니다. 세 운영체제를 한 번에 넣으면 생성 시간이 늘 뿐, 로그가 가리키는 파일은 하나면 충분합니다.

로그가 rhel-openssl-3.0.x를 찾을 때
generator client {
  provider      = "prisma-client-js"
  binaryTargets = ["native", "rhel-openssl-3.0.x"]
}

파일을 받았어도 빌드가 생성을 건너뛰면 없다

타깃을 적어도 prisma generate가 프리뷰 빌드에서 돌지 않으면 파일은 옛 것입니다. 프리즈마 넥스트 문서는 버셀이 의존성을 캐시하면 postinstall이 다음 배포에서 안 돈다고 적습니다. 그때 문구는 Prisma has detected that this project was built on Vercel에 가깝습니다. 엔진 파일을 못 찾는 줄과 같이 나올 수 있지만, 손댈 설정은 생성 시각입니다.

권장 스크립트는 postinstall에 prisma generate를 두는 것입니다. 캐시를 못 믿으면 빌드 명령 앞에 같은 명령을 붙입니다. 대시보드 빌드 명령에 붙이는 방법도 문서에 있습니다. 한국 시간으로 프리뷰를 자주 올리는 1인 프로젝트는, 스키마만 고치고 설치가 캐시되면 이 줄을 다시 만납니다.

생성 결과가 커스텀 output 폴더에 있으면, 그 폴더가 배포 번들에 들어가야 합니다. 로그는 번들이 .so.node를 결과물 옆으로 복사하지 못했다고 말합니다. 넥스트에서는 serverExternalPackages에 @prisma/client를 넣어 그 패키지를 번들 안으로 말지 않게 합니다. 문서는 serverExternalPackages입니다.

빌드마다 클라이언트를 다시 만든다
{
  "scripts": {
    "postinstall": "prisma generate",
    "build": "prisma generate && next build"
  }
}

자물쇠가 걸린 서버 캐비닛 문과 바닥의 케이블 트레이 — 엔진 파일은 잠긴 캐비닛처럼, 받은 타깃이 아니면 프리뷰가 열지 못합니다

P2028이나 연결 실패와 숫자가 다르다

쿼리가 데이터베이스까지 갔다면 엔진 파일은 이미 찾은 것입니다. P2028은 대화형 트랜잭션이 닫힌 뒤의 쿼리이고, 기본 timeout은 5000밀리초입니다. P1001은 호스트와 포트에 연결이 안 될 때입니다. 실패한 마이그레이션 기록은 P3009입니다. 이번 줄에는 그 코드가 없고, could not locate the Query Engine만 있습니다.

문장	의미	먼저 볼 칸
could not locate the Query Engine	그 런타임 파일이 번들 옆에 없음	binaryTargets, generate
P2028	트랜잭션이 이미 닫힘	timeout, 콜백 안의 tx
P1001	데이터베이스 주소에 연결 실패	호스트, 포트, 일시정지
built on Vercel, outdated client	캐시된 설치가 generate를 건너뜀	빌드 명령의 prisma generate

연결 문자열을 풀러 포트로 바꿔도 이 파일 오류는 그대로입니다. 주소는 엔진을 찾은 다음 문제입니다.

프리뷰 쿼리 전에 볼 다섯 줄

[ ] 로그의 런타임 문자열을 스키마 binaryTargets에 적었다
[ ] native를 남겨 로컬 맥 실행을 유지했다
[ ] provider가 prisma-client이면 libquery_engine을 찾지 않는지 import를 확인했다
[ ] postinstall 또는 build에 prisma generate가 있다
[ ] 넥스트가 @prisma/client를 번들 안으로 말지 않는지 봤다

연관 글은 P2028 트랜잭션, 쿠키 때문에 빌드가 멈추는 줄, 빈 환경 변수 주소입니다.

참고 자료

Prisma, binaryTargets | 운영체제별 엔진 이름, 기본값 native
Prisma, Next.js | 버셀 캐시와 prisma generate
Next.js, serverExternalPackages | 서버 패키지를 번들에서 빼기
Prisma, generators | prisma-client와 prisma-client-js

인용한 필드와 기본값은 2026년 10월 6일 공개 문서 기준입니다.

한국에서 혼자 넥스트와 프리즈마로 프리뷰를 올리면, 맥에서는 회원 조회가 되고 버셀 프리뷰의 첫 요청만 엔진 파일을 못 찾습니다. 데이터베이스를 서울 리전에 두었어도 연결 문자열은 그대로입니다. 바뀌는 것은 클라이언트 생성물이 어느 운영체제용으로 만들어졌는지입니다. 노트북에서 생성하면 그 노트북용 파일만 나오고, 리눅스 함수는 자기 이름과 같은 엔진 파일을 옆에서 찾다 실패합니다. 로그에 찍힌 런타임 이름을 스키마에 적고, 빌드 스크립트가 생성을 다시 실행해야 프리뷰 산출물에 그 파일이 들어갑니다. 생성 명령이 로컬에서만 초록이어도 배포 설치가 캐시되면 그 단계가 빠질 수 있으니, 빌드 로그에 생성이 있는지 확인합니다.

카카오 로그인 콜백이 서버 오류를 내도 토큰 주소부터 의심하지 마세요. 그 함수가 프리즈마를 처음 부를 때 엔진이 없으면 초기화에서 이미 죽습니다. 콜백 경로를 고치기 전에 오류 문장의 런타임 이름을 읽습니다. 트랜잭션이 닫혔다는 코드, 데이터베이스 호스트에 닿지 않는다는 코드와 파일 이름을 한 처방으로 묶지 않습니다. 국내 미리보기 주소와 로컬 주소가 다른 데이터베이스를 봐도, 엔진 파일이 없으면 행이 있기 전에 프로세스가 멈춥니다. 배포 로그에서 파일 이름을 읽기 전에 스키마를 통째로 갈아엎거나 연결 풀 숫자를 올리면, 같은 초기화 오류가 다음 배포에도 남습니다. 생성 로그에 타깃 이름이 찍혔는지 확인한 뒤에 쿼리 문을 고칩니다.

자주 묻는 질문

맥에서는 되는데 프리뷰만 엔진을 못 찾으면 무엇을 넣나요?

로그에 적힌 런타임 이름을 binaryTargets에 넣습니다. 버셀 노드에서 자주 보이는 문자열은 rhel-openssl-3.0.x입니다. native는 남겨 두고 prisma generate를 빌드에서 다시 실행하세요.

binaryTargets를 넣었는데도 같은 줄이면요?

프리뷰 빌드가 prisma generate를 건너뛰었는지 먼저 봅니다. 버셀은 설치를 캐시하면 postinstall이 다음 배포에서 안 돌 수 있습니다. 빌드 명령 앞에 prisma generate를 붙이세요. 그다음 번들이 .so.node를 빼먹었는지 봅니다.

프리즈마 7인데도 이 파일이 필요한가요?

provider가 prisma-client이면 쿼리 컴파일러를 쓰고 binaryTargets 칸이 없습니다. 로그가 libquery_engine을 말하면 아직 prisma-client-js 쪽 클라이언트를 import하고 있는 것입니다. 출력 경로와 import를 맞추세요.

알파인 컨테이너인데 rhel 타깃을 넣어도 되나요?

로그가 linux-musl-openssl-3.0.x를 말하면 그 이름을 넣습니다. rhel 파일은 알파인에서 열리지 않습니다. 문서 표의 OpenSSL 버전과 배포판을 로그 문자열에 맞추세요.

P2028과 같이 고치면 되나요?

아닙니다. P2028은 엔진을 찾은 뒤 트랜잭션이 닫힌 쿼리입니다. 이번 줄은 쿼리 전에 엔진 파일 자체가 없습니다. timeout을 늘려도 파일이 생기지 않습니다.

데이터베이스 주소를 풀러 포트로 바꾸면 해결되나요?

연결 주소는 엔진을 연 다음의 문제입니다. could not locate the Query Engine에는 호스트가 나오지 않습니다. 파일 타깃과 generate를 먼저 맞추세요.

프리뷰만 쿼리 엔진을 못 찾는 줄은 로그의 런타임 이름이 가리키는 .so.node가 번들 옆에 없다는 뜻입니다. binaryTargets에 그 이름을 넣고 빌드에서 prisma generate를 돌리면, 연결과 트랜잭션 제한을 보기 전에 이 칸이 갈립니다. 관련 글: P2028, Dynamic server usage, 엣지 런타임.

PrismaQuery EnginebinaryTargetsOpenSSL버셀프리뷰엔진백엔드

EXPLORE / Backend