はじめに

先日、Next.js 16が公開されたので早速、社内ツールや個人開発たちをアップグレードしました。

アップグレードによってESLint関連のエラーをはじめ、本記事のテーマであるPrismaとの連携エラーが発生しました。
そこで自身の備忘録や情報共有の意図から記事にしていきます。

対象サイトの技術構成とデプロイ先

技術構成

@eslint/eslintrc@3.3.1
@prisma/client@6.18.0
@types/node@24.9.1
@types/react-dom@19.2.2
@types/react@19.2.2
@types/uuid@10.0.0
eslint-config-next@16.0.0
eslint@9.38.0
jotai@2.15.0
next@16.0.0
prisma@6.18.0
react-dom@19.2.0
react@19.2.0
typescript@5.9.3
uuid@13.0.0

デプロイ先
Vercel

Prisma について

知っている方は飛ばしていただいて結構です。

PrismaとはORM（Object-Relational Mapping）の一種で、
簡潔に説明すると「SQLを知らなくても（書けなくても）、プログラムのコードだけでデータの追加・更新・検索などDBを操作できる」ツールです。

発生したPrismaとの連携エラー

はじめに、先のNext.js 16ページにあるUpgrade to Next.js 16:の以下コードを実施してアップグレードを行いました。

# Use the automated upgrade CLI
npx @next/codemod@canary upgrade latest

アップグレード自体は無事に済み、起動させてみるとPrismaに接続するAPIで500エラーが出ていました。
このエラー自体はアップグレードやアップデート、初期設定時などでよく見るタイプで、本記事で説明する連携エラーとは異なります。

これは、Prismaを生成し直すと大抵修復できます。

# Prismaクライアントを生成（更新）
npx prisma generate

余談ですが、Next.jsとPrismaを連携させるには以下のようにビルド時の設定も必要となります。

package.json

{
  "scripts": {
    "dev": "next dev",
-   "build": "next build",
+   "build": "prisma generate && next build",
    ...
    ..
    .
  }
}

アップグレード後は、ESLintをはじめ、手動チェックなど確認作業を通じて修正やリファクタリングを進めていきました。
そしてビルドも行い、無事にビルドエラーも出ないことを確認してデプロイ実施。

デプロイ先のVercelでも当然ビルドエラーは発生せず作業完了と思いながら本環境サイトを見に行くと500エラーが発生していたのです。

本環境でのPrismaとの連携エラー

ReactやNext.jsなどライブラリ・フレームワークあるあるですが、ログ出力されるエラーでは具体的なことは把握しづらいです。
ログ出力から判明したのはAPI接続における500エラーが出ている事実でした。

そこでVercelのダッシュボードを見に行き、当該サイトのエラーログを確認したところ、以下のような詳細情報が記載されていました。

Error [PrismaClientInitializationError]: 
Invalid `prisma.reservation.findMany()` invocation:


Prisma Client could not locate the Query Engine for runtime "rhel-openssl-3.0.x".

We detected that you are using Next.js, learn how to fix this: https://pris.ly/d/engine-not-found-nextjs.

This is likely caused by tooling that has not copied "libquery_engine-rhel-openssl-3.0.x.so.node" to the deployment folder.
Ensure that you ran `prisma generate` and that "libquery_engine-rhel-openssl-3.0.x.so.node" has been copied to "node_modules/.prisma/client".

We would appreciate if you could take the time to share some information with us.
Please help us by answering a few questions: https://pris.ly/engine-not-found-tooling-investigation

The following locations have been searched:
  /var/task/node_modules/.prisma/client
  /var/task/node_modules/@prisma/client
  /vercel/path0/node_modules/@prisma/client
  /tmp/prisma-engines
    at async E (.next/server/chunks/[root-of-the-server]__f5f624e3._.js:1:1553)
    at async d (.next/server/chunks/[root-of-the-server]__f5f624e3._.js:1:5037) {
  clientVersion: '6.18.0',
  errorCode: undefined,
  retryable: undefined
}

予想通り、原因はPrismaです。
しかし、先の通り生成し直して開発時は問題なく表示されていました。

今回、こういったケースが初めてだったので少し混乱しましたが、生成AI（Claude）に協力して ~~（助けて）~~ もらいながら対応を進めました。

原因と対応

先に結論として、このエラーの原因と対応を記載しておきます。

症状

Next.js 16へアップグレード後、開発環境では正常に動作しビルドも成功するが、Vercelへのデプロイ後に500エラーが発生

原因

Next.js 16ではファイルトレーシング（必要なファイルを自動検出する機能）が最適化され、使用されていないと判断されたファイルを積極的に除外するようになった。
その結果、Prismaのバイナリファイル（.so.node）がデプロイパッケージから除外され、実行時にエラーが発生していた。

Vercelの実行環境（AWS Lambda: RHEL系、OpenSSL 3.0.x）でlibquery_engine-rhel-openssl-3.0.x.so.nodeがないとデータベースクエリを実行できないようです。

対応方法

schema.prismaでバイナリターゲットを指定
Vercel（AWS Lambda）環境用のバイナリを生成するよう設定

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

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

next.config.mjs/jsでバイナリファイルをデプロイに含める
Next.jsに対して、Prismaのバイナリファイルをデプロイパッケージに含めるよう明示的に指示

/** @type {import('next').NextConfig} */
const nextConfig = {
   // Prismaのバイナリファイル(.so.node)をVercelデプロイ時に確実に含めるための設定
   // schema.prismaの binaryTargets で生成されたファイルがデプロイパッケージに含まれるようにする
+   outputFileTracingIncludes: {
+       '/api/**/*': ['./node_modules/.prisma/client/**/*'],
+       '/*': ['./node_modules/.prisma/client/**/*'],
   },
};

export default nextConfig;

補足

この問題はNext.js 15以前では発生していませんでした（ビルド最適化が寛容だったため？）
Vercel以外のサーバーレス環境（AWS Lambda、Google Cloud Functionsなど）でも同様の問題が発生する可能性あり

さいごに

今回の一件では、トラブルシューティングについての学びが多かったように感じます。

開発時は挙動に問題がなく、ビルドも無事に実施できている -> サイト・アプリ側での問題ではない
デプロイ先でもビルドは無事に実施できている -> Next.js（フレームワーク）側の問題ではない
本環境でAPI接続エラーが発生、ログ出力で簡易なエラー情報を確認し、デプロイ先のエラーログで詳細情報を確認
仮説をもとにデバッグ実施（AI活用するとむちゃ捗る）
AIを活用した振り返りの実施

個人的に最後のAIを活用した振り返りがかなり重要で、キャッチアップ効率が良いとも感じました。

フロントエンド開発は多くのライブラリやフレームワークに依存するのが一般的なので、それら起因のトラブルシューティングにも慣れておきたいですね。

この記事が、Next.js のアップグレード時における Prisma 連携エラーの解消に役立てると幸いです。

ここまで読んでいただき、ありがとうございました。