ERR_MODULE_NOT_FOUND, ESM 오류 해결 가이드
Node.js에서 import를 사용하다가 Error [ERR_MODULE_NOT_FOUND]라는 메시지를 만나면 파일이 분명 존재하는데 왜 찾지 못하는지 헷갈릴 수 있습니다. CommonJS의 require()를 사용하다 ES Module로 전환한 프로젝트에서 자주 마주치는 문제인데요.
ERR_MODULE_NOT_FOUND 오류는 Node.js가 import한 파일이나 패키지를 현재 모듈 해석 규칙에 따라 찾지 못했을 때 발생할 수 있습니다. 단순한 경로 오타뿐 아니라 파일 확장자, package.json의 type, npm 패키지 설치 여부까지 관련될 수 있습니다.
ES Module과 CommonJS의 차이부터 해결 순서까지 알아보겠습니다.
ERR_MODULE_NOT_FOUND 뜻은?
오류 이름 그대로 요청한 모듈을 찾지 못했다는 의미입니다. 예를 들어 다음과 같이 ES Module에서 파일을 가져온다고 가정해 보겠습니다.
import { sum } from "./math.js";
현재 위치를 기준으로 math.js가 존재하지 않거나 경로가 잘못됐다면 Node.js는 해당 모듈을 정상적으로 불러올 수 없습니다. 이때 ERR_MODULE_NOT_FOUND와 함께 찾지 못한 파일 정보가 표시될 수 있습니다.
따라서 가장 먼저 해야 할 일은 에러 메시지에서 정확히 어떤 파일이나 패키지를 찾지 못했다고 하는지 확인하는 것입니다.
ES Module에서 .js 확장자를 확인하세요
CommonJS 방식에 익숙하다면 상대 경로를 작성할 때 파일 확장자를 생략하는 습관이 있을 수 있습니다.
// CommonJS에서 자주 보던 형태
const math = require("./math");
하지만 Node.js의 ES Module에서 상대적인 파일 import를 작성할 때는 실제 파일 확장자를 포함한 경로가 필요할 수 있습니다.
// ES Module
import { sum } from "./math.js";
실제 파일이 math.js인데 ./math만 작성했다면 이를 가장 먼저 확인해 보세요. 브라우저용 번들러나 프레임워크에서 사용하던 import 작성법을 Node.js ESM 코드에 그대로 가져오면서 차이가 발생하는 경우도 있습니다.
ERR_MODULE_NOT_FOUND 파일 경로부터 확인하기
확장자가 정확하다면 다음은 상대 경로입니다. ./는 현재 파일이 있는 위치를 기준으로 하고 ../는 상위 폴더를 가리킵니다.
// 같은 폴더
import helper from "./helper.js";
// 한 단계 위
import helper from "../helper.js";
여기서 중요한 것은 터미널 위치가 아니라 import를 작성한 모듈 파일을 기준으로 상대 경로를 해석해야 한다는 점입니다. 폴더가 여러 단계로 나뉜 프로젝트에서는 이 기준을 혼동하기 쉽습니다.
파일명과 폴더명의 대소문자도 실제 이름과 일치하는지 확인하세요. 로컬에서는 발견하지 못했던 대소문자 문제가 다른 운영체제나 배포 환경에서 나타날 수도 있습니다.
npm 패키지에서 ERR_MODULE_NOT_FOUND가 난다면?
상대 파일이 아니라 외부 패키지를 import하다 오류가 발생했다면 해당 패키지가 현재 프로젝트에 설치되어 있는지 확인해야 합니다.
import express from "express";
express가 설치되어 있지 않다면 프로젝트 폴더에서 필요한 패키지를 설치합니다.
npm install express
이미 설치했다고 생각한다면 package.json과 node_modules를 확인하세요. 여러 프로젝트를 동시에 작업하는 경우 다른 폴더에서 npm install을 실행해 엉뚱한 프로젝트에 패키지가 설치된 경우도 있습니다.
package.json의 type: module 확인하기
Node.js 프로젝트에서 ES Module을 사용할 때 자주 확인하게 되는 설정이 package.json의 "type": "module"입니다.
{
"type": "module"
}
이 설정이 적용되는 범위에서는 일반적인 .js 파일을 ES Module 방식으로 다룰 수 있습니다. 반대로 프로젝트가 CommonJS를 기준으로 작성되어 있는데 일부 파일에서 ESM 문법을 섞으면 예상하지 못한 모듈 관련 오류를 만날 수 있습니다.
따라서 특정 오류 한 줄만 고치기 전에 현재 프로젝트가 ESM인지 CommonJS인지 먼저 파악하는 것이 중요합니다.
ES Module과 CommonJS 차이는?
두 방식의 가장 눈에 띄는 차이는 모듈을 가져오고 내보내는 문법입니다. ES Module은 import와 export를 사용하고, CommonJS는 주로 require()와 module.exports를 사용합니다.
| 불러오기 | import | require() |
| 내보내기 | export | module.exports |
| 대표 확장자 | .mjs | .cjs |
| package.json 예 | "type": "module" | "type": "commonjs" |
쉽게 기억하면 import/export = ESM, require/module.exports = CommonJS입니다.
다만 실제 Node.js 프로젝트에서는 파일 확장자와 package.json의 설정에 따라 각 파일이 어떤 모듈 방식으로 처리되는지가 결정되므로 전체 구성을 함께 확인해야 합니다.
폴더 이름만 import하면 왜 안 될까?
CommonJS나 특정 번들러 환경에서 사용하던 경로 해석 방식이 Node.js ESM에서도 똑같이 적용될 것이라고 생각하면 문제가 생길 수 있습니다. 예를 들어 로컬 디렉터리를 단순히 폴더 이름으로 import하는 코드는 환경에 따라 기대대로 해석되지 않을 수 있습니다.
// 모호한 경로에 의존하지 말고
import util from "./utils/index.js";
ESM에서는 가능하면 실제로 불러오려는 파일을 명확하게 지정하는 습관을 들이는 것이 좋습니다. 기존 CommonJS 프로젝트를 ESM으로 변경한 직후 오류가 여러 개 발생한다면 이런 import 경로들을 함께 점검해 보세요.
패키지는 있는데 import가 실패한다면?
npm 패키지가 분명 설치되어 있는데도 특정 내부 파일을 import할 때 문제가 생길 수 있습니다. 일부 패키지는 package.json의 exports 설정을 통해 외부에서 접근할 수 있는 경로를 제한하기 때문입니다.
따라서 패키지 내부의 임의 파일 경로를 직접 지정하기보다 해당 라이브러리가 공식적으로 제공하는 import 방식을 사용하는 것이 좋습니다. 패키지를 업데이트한 뒤 갑자기 import가 실패한다면 버전 변경과 export 구조도 확인해 보세요.
ERR_MODULE_NOT_FOUND 주요 원인 8가지
1. import 상대 경로를 잘못 작성한 경우
2. 파일명이나 폴더명에 오타가 있는 경우
3. 상대 import에서 필요한 파일 확장자가 빠진 경우
4. 파일명의 대소문자가 실제 파일과 다른 경우
5. 필요한 npm 패키지가 설치되지 않은 경우
6. 다른 프로젝트 폴더에 패키지를 설치한 경우
7. ES Module과 CommonJS 설정을 혼용한 경우
8. 패키지가 해당 내부 경로를 export하지 않는 경우
여러 원인이 있지만 가장 효율적인 방법은 에러 메시지에 나온 찾지 못한 대상 하나부터 추적하는 것입니다. 로컬 파일이라면 경로와 확장자를, 패키지라면 설치 여부와 package.json을 먼저 확인하면 됩니다.
ERR_MODULE_NOT_FOUND 해결 순서
오류가 나타났다고 바로 node_modules를 삭제할 필요는 없습니다. 가장 단순하고 자주 발생하는 원인부터 순서대로 점검해 보세요.
| 1단계 | 에러에서 찾지 못한 모듈 이름 확인 |
| 2단계 | 로컬 파일인지 npm 패키지인지 구분 |
| 3단계 | ./, ../ 상대 경로 확인 |
| 4단계 | 파일명·대소문자·.js 확장자 확인 |
| 5단계 | 외부 패키지라면 설치 상태 확인 |
| 6단계 | package.json의 type 설정 확인 |
| 7단계 | ESM과 CommonJS 혼용 여부 확인 |
| 8단계 | 패키지 exports 및 공식 import 방식 확인 |
Cannot find module과 차이는 무엇일까?
Cannot find module과 ERR_MODULE_NOT_FOUND는 모두 필요한 모듈을 찾지 못했다는 점에서는 비슷합니다.
하지만 ERR_MODULE_NOT_FOUND를 보고 있다면 Node.js의 ES Module 로딩 과정과 관련된 경로 및 설정을 특히 주의해서 살펴볼 필요가 있습니다.
따라서 이전에 require 기반 CommonJS에서 사용하던 해결법만 반복하기보다 import 경로의 확장자와 package.json의 모듈 설정을 함께 확인해 보세요. 오류 메시지에 표시된 URL이나 파일 경로도 중요한 단서가 됩니다.
require로 바꾸면 해결될까?
ESM에서 오류가 발생했다고 모든 import를 require()로 바꾸는 것은 좋은 해결 방법이 아닙니다. 프로젝트가 ES Module을 기준으로 구성되어 있다면 오히려 설정과 import 경로를 ESM 규칙에 맞추는 것이 자연스럽습니다.
반대로 기존 CommonJS 프로젝트를 유지해야 한다면 .cjs와 require 방식 등 현재 프로젝트에 맞는 구성을 사용하면 됩니다. 중요한 것은 두 방식 중 하나가 무조건 더 좋다는 것이 아니라 프로젝트의 모듈 시스템과 코드 작성 방식을 일치시키는 것입니다.
ERR_MODULE_NOT_FOUND 예방 방법
Node.js에서 ES Module을 사용한다면 상대 import 경로를 작성할 때 실제 파일명과 확장자를 정확하게 적는 습관을 들여보세요. 새로운 npm 패키지를 추가했다면 올바른 프로젝트 폴더에 설치했는지도 함께 확인하는 것이 좋습니다.
ERR_MODULE_NOT_FOUND가 나타났다면 먼저 “파일을 못 찾는 것인지, npm 패키지를 못 찾는 것인지”를 구분하세요. 파일이라면 경로·대소문자·확장자를 확인하고, 패키지라면 설치 상태와 공식적인 import 경로를 살펴보면 됩니다.
ESM 프로젝트라면 경로 → 확장자 → package.json → 패키지 설치 → exports 순서로 확인해 보세요. 무작정 node_modules를 재설치하거나 require로 변경하는 것보다 훨씬 빠르게 원인을 찾을 수 있습니다.