Error ini adalah salah satu masalah paling frustasi yang dihadapi developer ketika bekerja dengan Prisma ORM di lingkungan Node.js, terutama saat menggunakan ES Modules. Pesan error ini muncul secara tiba-tiba — kadang setelah fresh install, kadang setelah upgrade versi, dan kadang tanpa perubahan kode sama sekali. Artikel ini akan membedah error ini sampai ke akar-akarnya dan memberikan solusi permanen yang bisa Anda terapkan segera.
Membaca Pesan Errornya
Ketika error ini muncul, Anda akan melihat pesan lengkap yang kurang lebih seperti ini di terminal atau console:
SyntaxError: Named export 'PrismaClient' not found. The requested module '@prisma/client' does not provide an export named 'PrismaClient'
Dalam bahasa Indonesia sederhana, pesan ini berarti: Node.js mencoba mengimpor sesuatu bernama PrismaClient dari paket @prisma/client, tapi paket tersebut tidak menyediakan ekspor dengan nama itu. Ini bukan berarti paketnya tidak ada — paketnya terinstal, tapi ketika Node.js membuka isinya, ia tidak menemukan apa yang dicari.
Error ini muncul karena ada disconnect antara apa yang kode Anda minta dan apa yang sebenarnya tersedia di dalam modul @prisma/client. Modul @prisma/client sebenarnya adalah sebuah "shell" kosong — isinya yang sesungguhnya di-generate secara dinamis oleh Prisma CLI berdasarkan file schema.prisma Anda. Ketika proses generate ini belum berjalan, gagal, atau hasilnya rusak, maka ekspor PrismaClient tidak akan ada.
Contoh kode yang memicu error ini biasanya terlihat seperti berikut:
// Menggunakan named import dengan ES Modules
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()
Atau dalam CommonJS:
// Menggunakan named destructuring
const { PrismaClient } = require('@prisma/client')
Kedua pola di atas akan gagal jika modul @prisma/client tidak berisi ekspor bernama PrismaClient — dan itulah yang terjadi ketika client belum di-generate atau proses generate gagal.
Kenapa Ini Terjadi
Ada beberapa root cause yang paling sering menjadi biang kerok error ini. Berikut urutannya dari yang paling sering terjadi:
1. Prisma Client belum di-generate (prisma generate belum dijalankan). Ini adalah penyebab paling umum, terutama setelah npm install pertama kali atau setelah clone repository baru. Paket @prisma/client terinstal dari npm, tapi isinya masih kosong karena perintah prisma generate belum pernah dijalankan di mesin Anda. Tanpa proses generate, file JavaScript yang mendefinisikan class PrismaClient tidak pernah dibuat.
2. Hasil generate rusak atau hilang (corrupted .prisma/client). Folder .prisma/client di dalam node_modules berisi kode yang dihasilkan oleh prisma generate. Folder ini bisa rusak karena proses npm install yang menghapus dan menimpa node_modules, karena konflik versi, atau karena operasi file yang terputus di tengah jalan. Ketika folder ini rusak, ekspor PrismaClient menghilang.
3. Versi prisma CLI dan @prisma/client tidak sinkron. Jika Anda menggunakan prisma versi 5.x untuk menjalankan prisma generate, tapi @prisma/client di package.json masih versi 4.x (atau sebaliknya), hasil generate bisa tidak kompatibel dengan runtime. Ini sering terjadi ketika satu paket di-upgrade tapi yang lain tidak.
4. Konflik ESM vs CommonJS. Pada Node.js versi modern, ketika package.json Anda berisi "type": "module", Node.js akan memperlakukan semua .js sebagai ES Modules. Jika kode generated Prisma tidak kompatibel dengan mode ini — misalnya karena versi Prisma terlalu lama — maka named export tidak akan dikenali dengan benar.
5. Custom output path di schema.prisma yang tidak sesuai. Jika Anda mendefinisikan output = "../src/generated/client" di blok generator pada schema.prisma, maka client akan di-generate ke folder tersebut, bukan ke default node_modules/.prisma/client. Namun, kode Anda masih mengimpor dari '@prisma/client' yang justru mengarah ke lokasi default yang kosong.
Untuk memastikan penyebab mana yang Anda alami, lakukan pengecekan berurutan: pertama, cek apakah folder node_modules/.prisma/client ada dan berisi file index.js atau schema.prisma. Kedua, bandingkan versi prisma dan @prisma/client di package.json. Ketiga, cek apakah package.json Anda memiliki "type": "module". Keempat, periksa blok generator di schema.prisma untuk melihat apakah ada custom output path.
Langkah Perbaikan
Langkah 1: Generate ulang Prisma Client
Jalankan perintah berikut di root proyek Anda:
npx prisma generate
Output yang diharapkan:
Prisma schema loaded from prisma/schema.prisma
✔ Generated Prisma Client (5.x.x) to ./node_modules/.prisma/client in 123ms
You can now start using Prisma Client in your code:
import { PrismaClient } from '@prisma/client'
// or
const { PrismaClient } = require('@prisma/client')
Jika Anda melihat pesan ✔ di atas, berarti generate berhasil. Jika muncul error saat generate, catat error tersebut — itu adalah masalah lain yang harus diselesaikan terlebih dahulu (misalnya schema tidak valid).
Langkah 2: Bersihkan dan generate ulang (jika Langkah 1 gagal)
Jika generate berhasil tapi error masih muncul, kemungkinan hasil generate sebelumnya masih menempel. Bersihkan dulu:
rm -rf node_modules/.prisma
rm -rf node_modules/@prisma/client
npm install
npx prisma generate
Pada Windows PowerShell:
Remove-Item -Recurse -Force node_modules\.prisma
Remove-Item -Recurse -Force node_modules\@prisma\client
npm install
npx prisma generate
Langkah 3: Sinkronkan versi prisma dan @prisma/client
Cek versi di package.json:
npm ls prisma @prisma/client
Jika versi berbeda, sinkronkan:
npm install prisma@latest @prisma/client@latest
npx prisma generate
Output yang diharapkan menunjukkan kedua paket memiliki versi yang identik, misalnya keduanya 5.22.0.
Langkah 4: Jika menggunakan custom output path
Jika schema.prisma Anda memiliki custom output:
generator client {
provider = "prisma-client-js"
output = "../src/generated/client"
}
Maka impor Anda harus diubah sesuai:
// Salah - akan error karena @prisma/client kosong
import { PrismaClient } from '@prisma/client'
// Benar - mengimpor dari lokasi generate yang sesungguhnya
import { PrismaClient } from '../src/generated/client'
Atau, hapus baris output dari schema untuk menggunakan default path, lalu jalankan npx prisma generate lagi.
Verifikasi bahwa solusi berhasil
Setelah menjalankan langkah-langkah di atas, verifikasi dengan menjalankan aplikasi:
node index.js
Atau jika menggunakan framework:
npm run dev
Jika tidak ada error SyntaxError lagi dan aplikasi bisa melakukan query database, solusi sudah berhasil. Anda juga bisa membuat file tes sederhana:
// test-prisma.mjs
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()
console.log('Prisma Client initialized successfully!')
await prisma.$disconnect()
Jalankan dengan node test-prisma.mjs. Jika muncul pesan "Prisma Client initialized successfully!" tanpa error, berarti masalah sudah terselesaikan.
Perbaikan Permanen
Solusi-solusi di atas bersifat reaktif — Anda memperbaiki setelah error muncul. Untuk mencegah error ini kembali, Anda perlu menerapkan konfigurasi dan best practice berikut:
1. Tambahkan prisma generate sebagai postinstall hook
Tambahkan script berikut di package.json Anda:
{
"scripts": {
"postinstall": "prisma generate"
}
}
Dengan konfigurasi ini, setiap kali Anda atau siapa pun menjalankan npm install, perintah prisma generate akan otomatis dijalankan setelahnya. Ini menjamin bahwa Prisma Client selalu di-generate setiap kali node_modules diperbarui. Ini adalah fix permanen paling penting karena mengeliminasi penyebab #1 (client belum di-generate) secara otomatis.
2. Pin versi prisma dan @prisma/client agar selalu identik
Di package.json, pastikan kedua paket memiliki versi yang sama persis:
{
"devDependencies": {
"prisma": "5.22.0"
},
"dependencies": {
"@prisma/client": "5.22.0"
}
}
Gunakan versi eksplisit (tanpa ^ atau ~) untuk mencegah npm menginstal versi minor atau patch yang berbeda. Versi yang tidak sinkron adalah sumber bug yang sangat sulit dilacak karena error-nya tidak langsung menunjukkan bahwa versi adalah penyebabnya.
3. Commit file .prisma/client ke version control (opsional tapi efektif)
Beberapa tim memilih untuk menambahkan hasil generate ke version control dengan menambahkan konfigurasi berikut di schema.prisma:
generator client {
provider = "prisma-client-js"
output = "../src/generated/client"
}
Kemudian commit folder src/generated/client ke Git. Pendekatan ini memastikan setiap developer yang clone repository langsung mendapatkan Prisma Client tanpa perlu menjalankan prisma generate terlebih dahulu. Tambahkan node_modules/.prisma ke .gitignore dan pastikan yang di-commit hanya folder output custom tersebut.
4. Best practice untuk setup proyek baru
Saat membuat proyek Prisma baru, ikuti urutan ini:
mkdir my-project && cd my-project
npm init -y
npm install prisma @prisma/client
npx prisma init
# Edit schema.prisma sesuai kebutuhan
npx prisma generate
Jangan pernah melewatkan npx prisma generate setelah npm install. Dan selalu tambahkan postinstall hook seperti dijelaskan di poin 1.
5. Perbedaan antar OS
Pada Linux dan macOS, perintah rm -rf berjalan normal. Pada Windows, gunakan PowerShell dengan Remove-Item -Recurse -Force seperti ditunjukkan di Langkah 2. terus, pada Windows, path node_modules/.prisma/client terkadang tidak terbaca dengan benar oleh beberapa editor — pastikan Anda menjalankan perintah dari terminal yang sama dengan editor (bukan dari Git Bash yang memiliki path resolution berbeda). Pada WSL (Windows Subsystem for Linux), file yang diedit di Windows tapi dijalankan di WSL bisa mengalami masalah file watching — jika error muncul setelah edit schema, jalankan npx prisma generate ulang dari terminal WSL.
Langkah Lanjutan
Jika semua solusi di atas sudah dicoba tapi error masih muncul, ada beberapa kemungkinan yang lebih dalam yang perlu Anda periksa.
Cache Node.js yang bermasalah
Node.js memiliki module cache yang persisten. Terkadang, meskipun Anda sudah mengganti isi node_modules, Node.js masih membaca versi lama dari cache. Untuk mengatasi ini:
# Hapus cache Node.js
npm cache clean --force
# Bersihkan seluruh node_modules dan install ulang
rm -rf node_modules package-lock.json
npm install
npx prisma generate