"Cannot find module" hatası nasıl çözülür? Adım adım rehber

Kısa yanıt

“Cannot find module” hatası nasıl çözülür sorusunun kısa yanıtı şu: önce hata mesajının gösterdiği modül adını ve dosya yolunu okuyun, ardından modülün kurulu olup olmadığını (npm install), yazımın doğruluğunu ve ECMAScript modüllerinde dosya uzantısının eklenip eklenmediğini kontrol edin. Çoğu durumda node_modules klasörünü ve kilit dosyasını silip yeniden kurmak,

yanlış bir göreli yolu düzeltmek veya TypeScript’te path alias’ları gerçek yollara çevirmek sorunu birkaç dakika içinde giderir..

“Cannot find module” hatası neden çıkar ve mantığı nedir?

Node.js, bir dosyada require('paket-adi') veya import x from './dosya' satırını çalıştırdığında, önce bu ifadenin işaret ettiği yolu kendi modül çözümleme algoritmasıyla gerçek bir dosya yoluna çevirmeye çalışır. Göreli bir yol ise diskteki klasör yapısına bakar; bir paket adı ise sırayla node_modules klasörlerini, önce o anki dizinde, bulamazsa üst dizinlerde arar. Zincirin herhangi bir noktasında beklenen dosya diskte yoksa, Node.js aramayı durdurur ve terminale “Cannot find module” hatası basar.

Bu hatayla en sık karşılaşılan anlar belirli senaryolara denk gelir: bir projeyi klonladıktan sonra npm install çalıştırmadan uygulamayı başlatmak, bir paketi package.json’dan silip kodda referansını unutmak, dosya veya klasör adını yeniden adlandırırken import yolunu güncellememek ya da CommonJS’ten ECMAScript modüllerine geçerken eski require alışkanlıklarını import söz dizimine taşımak. Hata mesajının altındaki dosya yolu ve hata kodu (MODULE_NOT_FOUND veya ERR_MODULE_NOT_FOUND), sorunun kök nedenini doğrudan işaret eder; bu satırı okumadan rastgele yeniden kurulum denemek genellikle zaman kaybettirir.

Terminal çıktısını okumayı öğrenin

Node.js, hatayı verirken genellikle hangi dosyadan hangi yola gitmeye çalıştığını da yazdırır: “Cannot find module ’./utils/helpers’” gibi bir satır, arandığı dizini ve aranan dosya adını birlikte gösterir. Bu bilgi, sorunun bir paket mi yoksa kendi dosyanız mı olduğunu hemen ayırt etmenizi sağlar; paket adıysa kurulum eksikliğine, göreli bir yolsa (./ veya ../ ile başlıyorsa) dosya sisteminde bir uyumsuzluğa işaret eder.

En sık görülen “Cannot find module” senaryoları hangileri?

Senaryo	Tipik neden	İlk çözüm
Paket adıyla hata (require('paket-adi'))	Paket hiç kurulmamış veya node_modules eksik	npm install çalıştırın, paket adını package.json’da doğrulayın
Göreli yolla hata (./dosya veya ../klasor)	Dosya taşınmış, yeniden adlandırılmış veya yol yanlış yazılmış	Dosya yolunu disk yapısıyla karşılaştırın
ESM’de import sonrası hata (ERR_MODULE_NOT_FOUND)	Göreli import’ta dosya uzantısı eksik	.js veya .mjs uzantısını yola ekleyin
TypeScript derlemesi sonrası hata	tsconfig.json’daki path alias derleme çıktısında çözümlenmemiş	tsc-alias gibi bir dönüştürücü ekleyin
Monorepo’da paket bulunamıyor	Çalışma dizini (workspace) yanlış veya bağımlılık hoisting sorunu	npm install monorepo kökünden çalıştırın
Docker/CI’da yerelde çalışıp sunucuda hata	node_modules imaja kopyalanmamış veya .dockerignore yanlış	Dockerfile’da bağımlılık kurulum adımını kontrol edin

Cannot find module hatası nasıl çözülür?

Ki sıralama en düşük riskli adımdan en köklü çözüme doğru ilerler; her adımdan sonra uygulamayı yeniden çalıştırıp hatanın değişip değişmediğine bakmanız yeterlidir.

1. Modül adını, yazımını ve kurulumunu doğrulayın

Hata bir paket adıyla ilgiliyse önce package.json’da o paketin dependencies veya devDependencies altında listelendiğini kontrol edin. Listelenmiyorsa npm install paket-adi ile ekleyin. Listeleniyorsa ama hâlâ hata alıyorsanız, node_modules klasörü içinde o paketin gerçekten var olup olmadığına bakın; bazen bir kurulum yarıda kesilir ve package.json güncel olsa da dosyalar diske yazılmamış olur. Node.js büyük/küçük harfe duyarlıdır, bu yüzden require('Lodash') gibi yanlış bir yazım da aynı hatayı tetikler.

2. Node_modules ve kilit dosyasını sıfırdan kurun

Yarım kalmış bir kurulum veya bozuk bir önbellek, en yaygın nedenlerden biridir. node_modules klasörünü ve package-lock.json’u tamamen silip npm install komutunu sıfırdan çalıştırmak, bağımlılık ağacını baştan kurar. Bu işlem kaynak kodunuza dokunmaz; node_modules her zaman yeniden üretilebilir bir klasördür. CI/CD ortamında aynı sıfırlamayı npm ci ile yapmak, kilit dosyasını birebir esas alarak daha güvenilir bir sonuç verir.

3. ESM’de yol ve dosya uzantısı kurallarını uygulayın

package.json’da "type": "module" tanımlıysa veya dosya uzantınız .mjs ise, projeniz ECMAScript modülleri (ESM) kullanıyor demektir. ESM, CommonJS’in aksine göreli import’larda dosya uzantısını zorunlu tutar; import { helper } from './utils' satırı ESM’de çalışmaz, import { helper } from './utils.js' yazmanız gerekir. Node.js’in resmî hata dokümantasyonu, bu davranışı ve ilgili ERR_MODULE_NOT_FOUND kodunu ayrıntılı olarak açıklar. Bare import’larda (paket adıyla, uzantısız) bu kural geçerli değildir; sorun yalnızca kendi dosyalarınıza göreli yollarda ortaya çıkar.

4. TypeScript path alias ve tsconfig kaynaklı hataları çözün

tsconfig.json’da @/utils gibi kısayollar tanımladıysanız, bu ayar yalnızca TypeScript derleyicisine ve editörünüze (örneğin VS Code’a) yol gösterir. tsc ile JavaScript’e derlendikten sonra Node.js, çalışma zamanında bu alias’ı tanımaz ve “Cannot find module ’@/utils’” hatası verir. Çözüm, tsc-alias veya tsconfig-paths gibi bir araç ekleyerek derleme adımında alias’ları gerçek göreli yollara çevirmektir; aksi hâlde kod editörde hatasız görünse de üretim ortamında çalışmaz.

Docker ve deploy ortamında “Cannot find module” hatası

Yerel makinede sorunsuz çalışan bir uygulama, Docker imajında veya bir dağıtım platformunda (Vercel, Railway, kendi sunucunuz) aynı hatayı verebilir; bunun en sık nedeni node_modules’un imaja hiç kopyalanmaması veya .dockerignore dosyasının yanlışlıkla bu klasörü dışarıda bırakmasıdır. Dockerfile’da bağımlılık kurulum adımının (RUN npm ci) kaynak kodu kopyalamadan önce ayrı bir katmanda çalıştırılması, hem derleme süresini kısaltır hem de eksik kurulum riskini azaltır. Monorepo yapılarında ise çalışma dizini (workspace) kök dizinden farklı olduğunda bağımlılıklar yanlış klasöre kurulabilir; bu durumda npm install komutunu her zaman monorepo’nun kök dizininden çalıştırmak gerekir.

Ekip halinde bu hatayı azaltmanın yolları

“Cannot find module” hatası tek seferlik bir arıza değil, genellikle bağımlılık ve import disiplinindeki küçük bir tutarsızlığın belirtisidir. Ekiplerin package-lock.json’u her zaman Git’e commit etmesi, herkesin aynı bağımlılık ağacını kurmasını garanti eder. Dosya veya klasör adı değiştirilen her refactor’da, o dosyaya işaret eden tüm import’ların IDE’nin “yeniden adlandırma” (rename) özelliğiyle güncellenmesi, elle unutulan yolların önüne geçer. ESM’ye geçiş yapan projelerde, geçişin tek seferde ve tüm import’ları uzantılı hâle getirecek şekilde yapılması, yarım kalan geçişlerden kaynaklanan dağınık hataları engeller.

Sık yapılan hatalar

Hatanın gösterdiği dosya yolunu okumadan doğrudan node_modules’u silip yeniden kurmaya kalkmak, sorun bir paket kurulumu değil kendi kodunuzdaki yanlış bir yolsa zaman kaybettirir. ESM projelerinde import yollarına uzantı eklemeyi unutmak, özellikle CommonJS’ten geçiş yapan ekiplerde sık görülür. TypeScript path alias’larını üretim derlemesinde dönüştürmeden bırakmak, kodun yerelde (ts-node ile) çalışıp üretimde patlamasına yol açar. Son olarak, monorepo’larda bağımlılıkları yanlış paketin dizininden kurmak, hangi node_modules’un gerçekte kullanıldığını karıştırır.

Kontrol listesi

Önce hata mesajındaki dosya yolunun bir paket adı mı yoksa göreli bir yol mu olduğunu belirleyin. Paket adıysa package.json’da listelendiğini ve node_modules içinde gerçekten kurulu olduğunu doğrulayın. Göreli yolsa dosyanın disk üzerindeki gerçek konumuyla eşleştiğini kontrol edin. Projeniz ESM kullanıyorsa göreli import’larda dosya uzantısının eklendiğinden emin olun. TypeScript path alias kullanıyorsanız derleme çıktısında bu alias’ların gerçek yollara çevrildiğini kontrol edin. Hâlâ çözülmediyse node_modules ve kilit dosyasını silip sıfırdan kurun.

Sonraki adım

“Cannot find module” hatası, genellikle modül çözümleme zincirindeki tek bir kırık halkanın terminale yansımasıdır ve hata mesajını dikkatle okuyarak çoğu zaman birkaç dakikada giderilir. En kritik kural, mesajın gösterdiği dosya yolunu önce anlamak, sonra çözüm aramaktır. Projenizin bağımlılık yönetimini, derleme süreçlerini veya dağıtım mimarisini baştan sağlam kurmak isterseniz, grup şirketimiz Web Tasarım Ofisi yazılım altyapısı ve kod yönetimi konularında uçtan uca danışmanlık sağlıyor.

Node.js tabanlı projelerinizi profesyonel bir ekiple kurmak ya da mevcut altyapınızı sağlamlaştırmak için özel yazılım hizmetimizi inceleyebilir ya da bizimle iletişime geçebilirsiniz. Kurulum aşamasında karşılaşabileceğiniz diğer yaygın engelleri npm install hatası rehberimizde ve port already in use hatası rehberimizde ayrıntılı olarak ele alıyoruz.

Kaynaklar

• Node.js Docs, Errors, ERR_MODULE_NOT_FOUND, Node.js’in resmî hata referansında modül çözümleme hatalarının tanımı ve ESM’e özgü kurallar.