Prisma を使った開発中に「Cannot find module '@prisma/client'」というエラーに遭遇したことはありませんか。

このエラーは、Prisma Client が正しく生成されていない、またはインストールされていない場合に発生します。本記事では、このエラーの原因から具体的な復旧手順まで、段階的に解説していきますので、エラー解決の参考にしていただければと思います。

背景

Prisma は、Node.js と TypeScript のための ORM ツールで、データベース操作を型安全に行えることが大きな魅力です。

Prisma の仕組みを理解することで、エラーの原因も見えてきますね。

mermaidCopy codeflowchart TD
  schema["schema.prisma<br/>(スキーマ定義)"] -->|prisma generate| client["@prisma/client<br/>(自動生成)"]
  client -->|import| app["アプリケーション<br/>コード"]
  schema -->|prisma migrate| db[("データベース")]
  app -->|クエリ実行| db

Prisma の基本構成では、schema.prismaファイルにデータモデルを定義し、prisma generateコマンドを実行することで、型安全な Prisma Client が自動生成されます。

この Prisma Client はnode_modules​/​@prisma​/​clientディレクトリに配置され、アプリケーションコードからimport { PrismaClient } from '@prisma​/​client'としてインポートして使用するのが一般的な流れです。

データベース操作はすべてこのクライアントを経由して行われるため、Prisma Client が正しく生成されていないと、アプリケーションは動作しません。

課題

「Cannot find module '@prisma/client'」エラーは、以下のような状況で発生することがあります。

初めて Prisma をプロジェクトに導入した際、あるいは他の開発者が作成したプロジェクトをクローンした直後など、様々なタイミングで遭遇する可能性があるでしょう。

mermaidCopy codeflowchart LR
  trigger["トリガー"] --> case1["新規プロジェクト<br/>セットアップ"]
  trigger --> case2["git clone後<br/>の環境構築"]
  trigger --> case3["依存関係<br/>更新後"]
  trigger --> case4["node_modules<br/>削除後"]

  case1 --> error["Error: Cannot find<br/>module '@prisma/client'"]
  case2 --> error
  case3 --> error
  case4 --> error

エラーが発生する主な原因

#	原因	詳細
1	Prisma Client の未生成	prisma generateコマンドが実行されていない
2	パッケージの未インストール	yarn installが実行されていない、または失敗している
3	node_modules の破損	キャッシュの問題や不完全なインストール
4	バージョン不整合	Prisma のバージョンが複数混在している
5	ビルド環境の問題	CI/CD 環境や Docker コンテナ内での設定ミス

このエラーメッセージは以下のような形で表示されます。

typescriptCopy codeError: Cannot find module '@prisma/client'
Require stack:
- /path/to/your/project/src/index.ts
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:815:15)
    at Function.Module._load (internal/modules/cjs/loader.js:667:27)

エラーコードとしてはMODULE_NOT_FOUNDが返され、Node.js がモジュールを見つけられない状態を示しています。

解決策

このエラーを解決するには、段階的なチェックリストに沿って対処することが効果的です。

以下の手順を上から順番に試していくことで、ほとんどのケースで問題を解決できるでしょう。

mermaidCopy codestateDiagram-v2
  [*] --> Check1: エラー発生
  Check1: パッケージ確認
  Check2: generate実行
  Check3: 再インストール
  Check4: キャッシュクリア
  Check5: バージョン確認

  Check1 --> Check2: package.json確認OK
  Check2 --> Check3: generate実行済み
  Check3 --> Check4: 再インストール済み
  Check4 --> Check5: クリア済み
  Check5 --> [*]: 解決

  Check1 --> [*]: 解決
  Check2 --> [*]: 解決
  Check3 --> [*]: 解決
  Check4 --> [*]: 解決

解決手順の全体像

各ステップで問題が解決したかを確認しながら進めていくことで、無駄な作業を避けられます。

#	ステップ	実行コマンド	確認項目
1	パッケージ存在確認	-	package.json に prisma の記載があるか
2	依存関係インストール	yarn install	node_modules が生成されたか
3	Prisma Client 生成	yarn prisma generate	@prisma/client が生成されたか
4	node_modules 再構築	yarn cache clean && yarn install	クリーンな状態で再インストール
5	バージョン整合性確認	yarn list @prisma​/​client	バージョンが一致しているか

それぞれの手順について、具体的なコマンドと確認方法を見ていきましょう。

具体例

ステップ 1: package.json の確認

まず最初に、プロジェクトの package.json ファイルで Prisma が正しく定義されているかを確認します。

以下のように、devDependencies と dependencies の両方に Prisma 関連のパッケージが含まれている必要があります。

jsonCopy code{
  "devDependencies": {
    "prisma": "^5.0.0"
  },
  "dependencies": {
    "@prisma/client": "^5.0.0"
  }
}

上記のように、prisma（CLI）は devDependencies に、@prisma​/​client（ランタイム）は dependencies に配置するのが推奨されています。

バージョン番号は必ず一致させることが重要で、不整合があると予期しないエラーの原因になるでしょう。

ステップ 2: 依存関係のインストール

package.json の確認ができたら、依存関係をインストールします。

bashCopy codeyarn install

このコマンドにより、package.json に記載されたすべてのパッケージが node_modules ディレクトリにインストールされます。

インストールが完了したら、以下のコマンドで Prisma が正しくインストールされたかを確認しましょう。

bashCopy codeyarn prisma --version

バージョン情報が表示されれば、Prisma CLI のインストールは成功しています。

ステップ 3: Prisma Client の生成

次に、Prisma Client を生成するコマンドを実行します。

bashCopy codeyarn prisma generate

このコマンドは、schema.prisma ファイルを読み込んで、型定義を含む Prisma Client のコードを自動生成するものです。

実行すると以下のような出力が表示されるはずです。

textCopy codeEnvironment variables loaded from .env
Prisma schema loaded from prisma/schema.prisma

✔ Generated Prisma Client (5.0.0) to ./node_modules/@prisma/client in 123ms

「Generated Prisma Client」というメッセージが表示されれば、生成は成功しています。

生成されたファイルはnode_modules​/​@prisma​/​clientディレクトリに配置され、以下のような構造になっているでしょう。

textCopy codenode_modules/@prisma/client/
  ├── index.d.ts（型定義ファイル）
  ├── index.js（実装ファイル）
  └── ...その他の生成ファイル

ステップ 4: node_modules のクリーンアップと再インストール

上記の手順で解決しない場合は、node_modules と Yarn のキャッシュをクリアして、完全にクリーンな状態から再インストールを行います。

まず、既存の node_modules ディレクトリを削除しましょう。

bashCopy coderm -rf node_modules

次に、Yarn のキャッシュをクリアします。

bashCopy codeyarn cache clean

そして、lock ファイルも削除して依存関係を再解決させます。

bashCopy coderm yarn.lock

最後に、依存関係を再インストールします。

bashCopy codeyarn install

再インストール後、もう一度 Prisma Client を生成しましょう。

bashCopy codeyarn prisma generate

この一連の手順により、キャッシュの破損や依存関係の不整合によるエラーを解消できます。

ステップ 5: バージョンの確認と統一

複数の Prisma バージョンが混在している場合、エラーが発生することがあります。

以下のコマンドで、インストールされている Prisma のバージョンを確認しましょう。

bashCopy codeyarn list @prisma/client
yarn list prisma

出力結果で複数のバージョンが表示される場合は、package.json で明示的にバージョンを指定します。

jsonCopy code{
  "devDependencies": {
    "prisma": "5.0.0"
  },
  "dependencies": {
    "@prisma/client": "5.0.0"
  }
}

バージョンを固定したら、再度クリーンインストールを実行してください。

bashCopy codeyarn cache clean && rm -rf node_modules && yarn install
yarn prisma generate

これで、バージョンの不整合によるエラーも解消されるはずです。

ステップ 6: TypeScript プロジェクトでの追加確認

TypeScript を使用している場合は、tsconfig.json の設定も確認が必要になります。

以下のように、moduleResolution が適切に設定されているか確認しましょう。

jsonCopy code{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

特にmoduleResolutionがnodeに設定されていないと、モジュールの解決がうまくいかない場合があります。

また、@prisma​/​clientの型定義を確実に読み込むために、以下の設定も推奨されるでしょう。

jsonCopy code{
  "compilerOptions": {
    "types": ["node"]
  }
}

ステップ 7: Docker 環境での対処

Docker 環境で開発している場合は、コンテナ内で Prisma Client が生成されているかを確認する必要があります。

Dockerfile に以下のような記述を追加しましょう。

dockerfileCopy codeFROM node:18-alpine

WORKDIR /app

# 依存関係のコピーとインストール
COPY package.json yarn.lock ./
RUN yarn install

# スキーマファイルのコピー
COPY prisma ./prisma/

# Prisma Clientの生成
RUN yarn prisma generate

# アプリケーションコードのコピー
COPY . .

重要なのは、yarn prisma generateをCOPY . .の前に実行することです。

これにより、アプリケーションコードが Prisma Client に依存する前に、確実に生成が完了します。

docker-compose.yml を使用している場合は、以下のようにコマンドを指定することもできるでしょう。

yamlCopy codeversion: '3.8'
services:
  app:
    build: .
    command: sh -c "yarn prisma generate && yarn start"
    volumes:
      - ./prisma:/app/prisma

ステップ 8: CI/CD 環境での対処

GitHub Actions や GitLab CI などの CI/CD 環境では、ビルドステップで Prisma Client の生成を明示的に実行する必要があります。

GitHub Actions の場合は、以下のようなワークフローを設定しましょう。

yamlCopy codename: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

次に、依存関係のインストールと Prisma Client の生成を行います。

yamlCopy code- name: Install dependencies
  run: yarn install

- name: Generate Prisma Client
  run: yarn prisma generate

- name: Run tests
  run: yarn test

この順序を守ることで、テスト実行前に必ず Prisma Client が生成されるようになります。

キャッシュを活用することで、ビルド時間を短縮することもできるでしょう。

yamlCopy code- name: Cache node modules
  uses: actions/cache@v3
  with:
    path: |
      node_modules
      ~/.cache/yarn
    key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}

エラーパターン別の解決フロー

実際のエラーメッセージから、どのステップを重点的に実施すべきかを判断できます。

#	エラーメッセージ	推奨される対処
1	Cannot find module '@prisma​/​client'	ステップ 2, 3 を実施
2	PrismaClient is unable to be run in the browser	環境変数の確認、サーバーサイドでの実行を確認
3	@prisma​/​client did not initialize yet	ステップ 3 を再実行
4	The postinstall script failed	ステップ 4 でクリーンインストール
5	prisma generate - command not found	ステップ 1, 2 を確認

予防策とベストプラクティス

一度エラーを解決した後は、再発防止のための設定を行うことをお勧めします。

package.json に postinstall スクリプトを追加することで、依存関係インストール後に自動的に Prisma Client が生成されるようになるでしょう。

jsonCopy code{
  "scripts": {
    "postinstall": "prisma generate"
  }
}

このスクリプトにより、yarn installを実行するだけで自動的にprisma generateも実行されます。

チーム開発では特に有効で、新しくプロジェクトに参加したメンバーがエラーに遭遇することを防げますね。

また、.gitignore には必ず node_modules を含めておきましょう。

textCopy codenode_modules/
.env

Prisma Client は自動生成されるファイルなので、Git で管理する必要はありません。

トラブルシューティングの追加 Tips

上記の手順でも解決しない場合は、以下の確認も行ってみてください。

権限の確認

ファイルシステムの権限が不足している場合、Prisma Client の生成に失敗することがあります。

bashCopy codels -la node_modules/@prisma/

権限が不足している場合は、以下のコマンドで修正できるでしょう。

bashCopy codesudo chown -R $USER:$USER node_modules

Node.js バージョンの確認

Prisma は特定の Node.js バージョンを要求する場合があります。

bashCopy codenode --version

推奨されるのは Node.js 16 以上で、それより古いバージョンを使用している場合はアップグレードを検討しましょう。

メモリ不足の確認

大規模なスキーマの場合、Prisma Client の生成時にメモリ不足が発生することがあります。

bashCopy codeNODE_OPTIONS=--max-old-space-size=4096 yarn prisma generate

このコマンドでメモリ上限を増やすことができ、生成が成功する可能性が高まります。

まとめ

「Cannot find module '@prisma/client'」エラーは、Prisma を使用する際に頻繁に遭遇するエラーの一つです。

しかし、本記事で紹介したチェックリストに沿って対処することで、ほとんどのケースで解決できるでしょう。

解決のための重要ポイント

• package.json で Prisma のバージョンを確認し、一致させること
• yarn installとyarn prisma generateを確実に実行すること
• node_modules のクリーンアップで多くの問題が解決すること
• Docker・CI/CD 環境では生成タイミングに注意すること
• postinstall スクリプトで自動生成を設定すると予防になること

エラーが発生した際は、焦らず一つずつ手順を確認していくことが大切です。

この記事が、Prisma での開発をスムーズに進める手助けになれば幸いですね。

関連リンク

• Prisma 公式ドキュメント
• Prisma Client API リファレンス
• Prisma GitHub リポジトリ
• Prisma トラブルシューティングガイド
• Node.js 公式サイト
• Yarn 公式ドキュメント