ERR_MODULE_NOT_FOUND ve Node.js ERR_* Hata Kodları

Hatayı mesajla değil error.code ile tanıyın

Node.js belgeleri bu konuda nettir: error.message metni herhangi bir sürümde değişebilir, error.code ise yalnızca ana sürümler arasında değişir. Bu yüzden hatayı tanımak için mesajda metin aramak yerine kodu karşılaştırın. Node.js'in ürettiği tüm hatalar standart Error sınıfından türer, ama sınıfı hatanın türüne göre değişir: yanlış tip için TypeError, aralık dışı değer için RangeError, modül bulunamadığında düz Error kullanılır.

try {
  await import('olmayan-paket');
} catch (err) {
  if (err.code === 'ERR_MODULE_NOT_FOUND') {
    console.log('paket kurulu değil');
  } else {
    throw err; // tanımadığınız hatayı yutmayın
  }
}
// çıktı: paket kurulu değil

Yakalanmamış bir hatanın ilk satırı Error [ERR_MODULE_NOT_FOUND]: ... biçimindedir: önce sınıf adı, köşeli parantez içinde kod, ardından mesaj gelir. Altında yığın izi ve hata nesnesinin ek alanları yazılır. JavaScript dilinin kendi hata sınıfları (ReferenceError, SyntaxError) ve try/catch kullanımı için JavaScript hata yönetimi ve sık görülen JavaScript hata mesajları yazılarına bakabilirsiniz.

ERR_MODULE_NOT_FOUND: modül bulunamadı

Aşağıdaki giriş dosyası aynı klasörde olmayan bir modülü içe aktarıyor. Modül grafiği çalışmadan önce bağlandığı için hata, ilk satır bile çalışmadan fırlatılır ve süreç 1 koduyla çıkar.

// giris.mjs
import { topla } from './matematik.js';
console.log(topla(1, 2));

$ node giris.mjs
node:internal/modules/esm/resolve:241
    throw new ERR_MODULE_NOT_FOUND(
          ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/kullanici/proje/matematik.js' imported from /home/kullanici/proje/giris.mjs
    at finalizeResolution (node:internal/modules/esm/resolve:241:11)
    ...
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///home/kullanici/proje/matematik.js'
}

Node.js v26.13.0

Mesajın en yararlı kısmı iki mutlak yoldur: aranan dosya ve onu içe aktaran dosya. Göreli yollar, içe aktaran dosyanın konumuna göre çözülür, çalışma dizinine göre değil. Hata nesnesindeki url alanı aranan dosyanın tam URL'sini verir. ESM'de dosya ve klasör yollarını güvenli kurmanın yolu için import.meta.dirname ve filename yazısına bakın.

Aynı hatayı farklı nedenlerle görebilirsiniz. Aşağıdaki betik, hata kodu üreten altı yaygın içe aktarma biçimini tek tek deniyor ve her birinin sınıfını ve kodunu yazdırıyor.

// kodlar.mjs
const denemeler = {
  paketYok: () => import('olmayan-paket'),
  dosyaYok: () => import('./yardimci.mjs'),
  uzantisiz: () => import('./lib/index'),
  klasor: () => import('./lib'),
  disaAcilmamis: () => import('paket/dahili/yardimci.js'),
  bilinmeyenUzanti: () => import('./veri.txt'),
};

for (const [ad, fn] of Object.entries(denemeler)) {
  try {
    await fn();
    console.log(ad, 'yüklendi');
  } catch (err) {
    console.log(ad, '|', err.constructor.name, '|', err.code);
  }
}
// çıktı: paketYok | Error | ERR_MODULE_NOT_FOUND
// çıktı: dosyaYok | Error | ERR_MODULE_NOT_FOUND
// çıktı: uzantisiz | Error | ERR_MODULE_NOT_FOUND
// çıktı: klasor | Error | ERR_UNSUPPORTED_DIR_IMPORT
// çıktı: disaAcilmamis | Error | ERR_PACKAGE_PATH_NOT_EXPORTED
// çıktı: bilinmeyenUzanti | TypeError | ERR_UNKNOWN_FILE_EXTENSION

Bu denemede lib/index.js dosyası gerçekten var, ama uzantısız yazılan ./lib/index yine bulunamadı. ESM belgesi bunu açıkça kural olarak koyar: import ile göreli veya mutlak bir yol çözülürken dosya uzantısı zorunludur ve klasör indeksleri de ./startup/index.js gibi tam yazılmalıdır. CommonJS'teki uzantı tamamlama ESM'de yoktur. Paket adıyla yapılan içe aktarmada ise mesaj farklıdır; olmayan-paket için "Cannot find package 'olmayan-paket' imported from ..." yazar. Bu ayrım, sorunun yolda mı yoksa kurulumda mı olduğunu hızla anlamanızı sağlar.

MODULE_NOT_FOUND: CommonJS tarafı

require() bir dosyayı bulamadığında fırlatılan hata MODULE_NOT_FOUND kodunu taşır; önünde ERR_ yoktur. Hata nesnesinde v12.0.0 ile eklenen requireStack alanı bulunur: bu dizi, başarısız require() çağrısına giden modül zincirini gösterir ve iç içe bağımlılıklarda sorunun hangi dosyadan başladığını bulmayı kolaylaştırır.

// cjs.cjs
try {
  require('./yok');
} catch (err) {
  console.log(err.code, err.requireStack);
  console.log(err.message.split('\n')[0]);
}
// çıktı: MODULE_NOT_FOUND [ '/home/kullanici/proje/cjs.cjs' ]
// çıktı: Cannot find module './yok'

İlginç bir ayrıntı: node yok.mjs gibi var olmayan bir giriş dosyası verdiğinizde, dosya .mjs uzantılı olsa bile hata MODULE_NOT_FOUND olur ve requireStack boş bir dizidir. Bunun nedeni, CLI belgesine göre giriş noktası dizesinin önce require() ile istenmiş gibi çözülmesidir. CommonJS çözümleme algoritmasının ayrıntıları require ve module.exports yazısında.

ERR_UNSUPPORTED_DIR_IMPORT ve ERR_PACKAGE_PATH_NOT_EXPORTED

import './lib' gibi bir klasörü içe aktarmak ESM'de desteklenmez ve ERR_UNSUPPORTED_DIR_IMPORT fırlatır. Mesaj "Directory import '/home/kullanici/proje/lib' is not supported resolving ES modules imported from ..." biçimindedir. Belgedeki çözüm ya dosyayı tam yoluyla (./lib/index.js) içe aktarmak ya da paketinizin package.json dosyasında exports alanıyla bir alt yol tanımlayıp paketi kendi adıyla içe aktarmaktır.

ERR_PACKAGE_PATH_NOT_EXPORTED ise bir paketin içindeki bir dosyaya doğrudan erişmeye çalıştığınızda görülür. Paket exports alanını tanımladıysa yalnızca orada listelenen alt yollar dışarıdan içe aktarılabilir; geri kalan dosyalar kapsüllenmiştir. Örneğimizdeki paket yalnızca "." girişini dışa açıyor:

{
  "name": "paket",
  "type": "module",
  "exports": {
    ".": "./ana.js"
  }
}

Bu durumda import 'paket/dahili/yardimci.js' çağrısı, dosya diskte var olsa bile şu mesajla reddedildi: "Package subpath './dahili/yardimci.js' is not defined by "exports" in /home/kullanici/proje/node_modules/paket/package.json imported from ...". Paket sahibi değilseniz yapılacak doğru şey, paketin dışa açtığı API'yi kullanmaktır. Paketin sahibiyseniz ilgili alt yolu exports içine ekleyin. Bu alanın tüm biçimleri package.json exports ve imports yazısında.

ERR_UNKNOWN_FILE_EXTENSION

ES modül yükleyicisi her dosya uzantısını tanımaz. import './veri.txt' denediğimizde hata TypeError sınıfında ve "Unknown file extension ".txt" for /home/kullanici/proje/veri.txt" mesajıyla geldi. Bu hata genellikle iki durumda görülür: metin ya da veri dosyasını modül gibi içe aktarmaya çalışmak ve tanınmayan bir uzantıyı giriş dosyası olarak çalıştırmak. Bir metin dosyasının içeriğine ihtiyacınız varsa onu fs.readFile ile okuyun (readFile ile dosya okuma). JSON dosyaları için ESM belgesi import veri from './veri.json' with { type: 'json' } biçimindeki içe aktarma özniteliğini gösteriyor; öznitelik eksik olursa bu kez ERR_IMPORT_ATTRIBUTE_MISSING alırsınız.

ERR_REQUIRE_ESM ve ERR_REQUIRE_ASYNC_MODULE

Eski rehberlerde sıkça geçen ERR_REQUIRE_ESM, CommonJS kodunun require() ile bir ES modülü yüklemeye çalıştığını bildirirdi. Belgeler bu kodu artık Stability 0 (kullanımdan kaldırılmış) olarak işaretliyor, çünkü require() senkron ES modüllerini varsayılan olarak yükleyebiliyor. Bu değişiklik v23.0.0, v22.12.0 ve v20.19.0 sürümlerine işlendi. Bugün karşılaşacağınız asıl hata ERR_REQUIRE_ASYNC_MODULE: yüklemeye çalıştığınız ES modülü üst düzey await içeriyorsa senkron require() onu tamamlayamaz.

// tla.mjs
await new Promise((r) => setTimeout(r, 10));
export const hazir = true;

// esm-sync.mjs
export const selam = 'merhaba';

// cjs.cjs (devamı)
try {
  require('./tla.mjs');
} catch (err) {
  console.log(err.code);
}
const { selam } = require('./esm-sync.mjs');
console.log(selam);
// çıktı: ERR_REQUIRE_ASYNC_MODULE
// çıktı: merhaba

Üst düzey await içermeyen esm-sync.mjs sorunsuz yüklendi. Çözüm iki yönlüdür: ya modüldeki üst düzey await kaldırılır, ya da CommonJS tarafında require() yerine asenkron import() kullanılır. Hangi modülün sorun çıkardığını bulmak için --experimental-print-required-tla bayrağı, hata yakalanmadığında üst düzey await konumlarını stderr'e yazar. v26.5.0 ile hata nesnesine requireStack ve topLevelAwaitLocations alanları eklendi; ikincisi yalnızca bu bayrakla doldurulur. İki modül sisteminin birlikte çalışması CommonJS ve ESM farkı yazısında ayrıntılı anlatılıyor.

Argüman doğrulama hataları

Node.js API'leri aldıkları argümanları hemen doğrular ve sorun varsa çağrının yapıldığı anda senkron olarak hata fırlatır. Bu hatalar genellikle bir programlama hatasına işaret eder: yanlış tipte değer, desteklenmeyen bir seçenek ya da aralık dışı bir sayı. Aşağıdaki örnek dört tipik durumu gösteriyor.

// arg.mjs
import path from 'node:path';
import { Buffer } from 'node:buffer';
import { readFileSync } from 'node:fs';
import { EventEmitter } from 'node:events';

const denemeler = {
  tip: () => path.join('a', 42),
  aralik: () => Buffer.alloc(-1),
  deger: () => readFileSync('veri.txt', { encoding: 'utf-9' }),
  emitter: () => new EventEmitter().emit('error', 'sadece metin'),
};
for (const [ad, fn] of Object.entries(denemeler)) {
  try {
    fn();
  } catch (err) {
    console.log(ad, '|', err.name, '|', err.code);
    console.log('  ', err.message);
  }
}
// çıktı: tip | TypeError | ERR_INVALID_ARG_TYPE
// çıktı:    The "path" argument must be of type string. Received type number (42)
// çıktı: aralik | RangeError | ERR_OUT_OF_RANGE
// çıktı:    The value of "size" is out of range. It must be >= 0 && <= 9007199254740991. Received -1
// çıktı: deger | TypeError | ERR_INVALID_ARG_VALUE
// çıktı:    The argument 'encoding' is invalid encoding. Received 'utf-9'
// çıktı: emitter | Error | ERR_UNHANDLED_ERROR
// çıktı:    Unhandled error. ('sadece metin')

Mesajlar hangi argümanın sorunlu olduğunu ve ne alındığını açıkça yazar. ERR_INVALID_ARG_TYPE yanlış tipte bir argümanı, ERR_INVALID_ARG_VALUE tipi doğru ama değeri desteklenmeyen bir argümanı, ERR_OUT_OF_RANGE ise kabul edilen aralığın dışında kalan bir değeri anlatır. Belgeye göre ERR_MISSING_ARGS yalnızca zorunlu bir argüman hiç verilmediğinde ve func(undefined) ile func() arasında fark gözetildiğinde kullanılır; çoğu yerleşik API'de bu iki çağrı aynı sayılır ve yerine ERR_INVALID_ARG_TYPE görülür.

Son satırdaki ERR_UNHANDLED_ERROR, bir EventEmitter üzerinde 'error' olayı dinleyicisiz yayıldığında ortaya çıkar. Yayılan değer bir Error nesnesi olsaydı o nesnenin kendisi fırlatılırdı; burada düz bir metin verdiğimiz için Node.js onu bu kodla sarmaladı. 'error' olayının davranışı EventEmitter kullanımı yazısında.

Sık karşılaşılan diğer kodlar

Aşağıdaki kodların açıklamaları errors.html sayfasındaki tanımlardan özetlendi. Kodların tam listesi çok uzundur; burada günlük geliştirmede en çok rastlananları topladık.

Tablodaki konuların ayrıntılı yazıları: http modülü ile sunucu, stream nedir, pipeline ve backpressure, URL ve URLSearchParams, izin modeli, node:test, AbortController. ABORT_ERR kodunun ERR_ önekini taşımamasının nedeni, belgeye göre web platformundaki AbortError ile uyumlu olmaktır; iptal hatalarını tanımak için err.name === 'AbortError' kontrolü yeterlidir.

Sık yapılan hatalar

Hata mesajında metin aramak. err.message.includes('Cannot find') gibi kontroller bir sonraki sürümde bozulabilir. Her zaman err.code değerini karşılaştırın.

MODULE_NOT_FOUND ile ERR_MODULE_NOT_FOUND'u karıştırmak. İlki CommonJS require(), ikincisi ES modül yükleyicisinden gelir. Hem CommonJS hem ESM kullanan bir kodda iki kodu da kontrol etmeniz gerekebilir.

ESM'de uzantıyı yazmamak. TypeScript veya paketleyici alışkanlığıyla ./yardimci yazmak, Node.js'in doğrudan çalıştırdığı ESM kodunda ERR_MODULE_NOT_FOUND üretir. Göreli yolları her zaman uzantısıyla yazın.

Paketin iç dosyalarını içe aktarmak. exports tanımlı bir paketin iç yolunu kullanmak ERR_PACKAGE_PATH_NOT_EXPORTED verir ve paket güncellendiğinde kırılmaya açıktır. Paketin dışa açtığı giriş noktalarını kullanın.

Tanımadığınız hatayı yutmak. Belirli bir kodu yakalayıp geri kalan her şeyi sessizce görmezden gelmek, gerçek hataları gizler. Beklemediğiniz kodları yeniden fırlatın; yakalanmayan hataların nasıl ele alınacağı uncaughtException ve unhandledRejection yazısında.

Sık Sorulan Sorular

ERR_MODULE_NOT_FOUND alıyorum ama dosya orada, neden?

En olası neden uzantının eksik olması ya da yolun içe aktaran dosyaya göre değil çalışma dizinine göre düşünülmesidir. Mesajdaki mutlak yolu diskteki dosyayla karşılaştırın; büyük küçük harf farklarını da kontrol edin.

ERR_REQUIRE_ESM hâlâ görülür mü?

Belgelere göre bu kod kullanımdan kaldırıldı, çünkü güncel sürümlerde require() senkron ES modüllerini yükleyebiliyor. Üst düzey await içeren bir modülde bunun yerine ERR_REQUIRE_ASYNC_MODULE fırlatılır.

Tüm ERR_* kodlarının listesini nerede bulurum?

nodejs.org/api/errors.html sayfasındaki "Node.js error codes" bölümü güncel listeyi verir. "Legacy Node.js error codes" bölümündeki kodlar ise tutarsız bulunduğu ya da kaldırıldığı için kullanımdan kaldırılmış sayılır.

Kendi hatalarıma da code alanı eklemeli miyim?

Belgeler bunu zorunlu tutmaz, ama aynı mantık sizin kodunuz için de geçerlidir: değişebilecek mesaj yerine sabit bir kodla hatayı tanımlamak, onu yakalayan kodu daha dayanıklı yapar. Kendi kodlarınız için ERR_ öneki yerine projenize özgü bir önek seçin.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Node.js öğrenme rehberi · Sistem hataları: ENOENT, EADDRINUSE · CommonJS ve ESM farkı · package.json exports · JavaScript hata yönetimi