ERR_MODULE_NOT_FOUND

확인

1. 오류 객체 또는 로그에서 error.code 값을 확인합니다.
2. 값이 ERR_MODULE_NOT_FOUND와 일치하는지 비교합니다.
3. 오류 스택 또는 로그에서 해석하지 못한 import 지정자와 이를 요청한 파일을 기록합니다.
4. 상대 경로·파일 확장자·대소문자와 package.json의 의존성 선언을 현재 작업 트리에서 확인합니다.

Node.js는 오류 메시지가 버전 사이에 변경될 수 있으므로, 오류 식별에는 error.message 대신 error.code 사용을 안내합니다.

재확인과 주의

경로 또는 의존성 선언 한 항목을 수정한 뒤 같은 진입점으로 다시 실행해 error.code가 사라졌는지 확인합니다. package.json, lockfile, import 경로를 한 번에 바꾸지 말고 프로젝트의 기존 패키지 관리자를 사용하세요.

출처

• Node.js Errors: ERR_MODULE_NOT_FOUND (새 창에서 열림)

관찰값 기록

문제가 발생한 URL 또는 화면, 표시 시각, 운영 환경과 최근 변경 사항을 먼저 기록합니다. 화면이나 로그에 오류 문구가 일부만 보이면 앞뒤 문장을 보존하고 비밀번호·토큰·쿠키·개인정보는 가립니다.

다음 항목을 실제 값과 함께 확인합니다.

1. 오류 객체 또는 로그의 error.code가 ERR_MODULE_NOT_FOUND와 정확히 일치하는지 확인합니다.
2. 오류가 import 작업 또는 프로그램 진입점 로드 중 발생했는지 확인합니다.
3. 오류 스택 또는 로그에서 해석하지 못한 import 지정자와 이를 요청한 파일을 기록합니다.
4. 상대 경로·파일 확장자·대소문자와 package.json의 의존성 선언을 현재 작업 트리에서 확인합니다.
5. 경로 또는 의존성 선언 한 항목을 수정한 뒤 같은 진입점으로 다시 실행해 error.code가 사라졌는지 확인합니다.

판정 기준

오류 문구가 일치해도 같은 원인이 확정되는 것은 아닙니다. 웹서버·런타임·운영체제·플랫폼과 최근 변경 사항을 비교하고, 기대한 관찰값이 나오지 않으면 다음 단계로 넘어가지 않습니다. 이 문서는 출처가 확인한 범위만 설명하며, 범위를 벗어난 원인과 조치는 단정하지 않습니다.

안전한 다음 확인

설정·권한·데이터를 변경하기 전에 백업과 되돌리기 방법을 기록합니다. 운영 환경의 방화벽 전체 해제, 인증서 검증 우회, 데이터 삭제, 비밀값 공개를 기본 조치로 사용하지 않습니다. 확인 결과가 문서의 조건과 다르면 관련 Platform·Component 문서와 공식 출처를 먼저 확인합니다.

원인 분포

[Observation] 입력된 6건의 사례에서는 다음 원인이 관찰되었습니다.

원인	관측 사례 수
ESM import가 NODE_PATH를 패키지 탐색 경로로 사용하지 않음	1
import 경로와 실제 파일명의 대소문자 불일치	1
TypeScript ESM 출력 기준의 상대 import 확장자 누락	1
ESM import.meta.resolve()가 반환한 file:// cacheHandler 경로의 잘못된 결합	2
Vercel @vercel/og Edge 배포에서 WASM 파일 누락	1

[Observation] 위 분포는 수집된 6건의 사례에서 관찰된 비율이며, 실제 발생 빈도를 의미하지 않습니다.

오진 함정

• [Observation] Windows에서 정상 동작한 import가 Linux에서도 정상이라고 판단하면 파일명 대소문자 불일치를 놓칠 수 있습니다.
• [Observation] ts-node에서 재현되지 않는다고 해서 컴파일 후 실행되는 JavaScript의 모듈 해석 문제를 배제할 수 없습니다.
• [Observation] 전역 패키지가 설치되어 있어도 ESM import가 NODE_PATH를 사용하지 않으면 패키지를 찾지 못할 수 있습니다.
• [Observation] Next.js ESM 설정에서 import.meta.resolve()가 반환한 file:// URL을 일반 파일 경로처럼 결합하면 .next/file:/ 형태의 잘못된 경로가 만들어질 수 있습니다.
• [Observation] Vercel Edge API에서 WASM 파일 누락이 발생하면 패키지 버전과 배포 산출물 포함 여부를 함께 확인해야 합니다.

환경 매트릭스

환경	관찰된 조건	결과
Node.js 20.11, ESM	전역 설치된 express import, NODE_PATH 탐색 기대	ERR_MODULE_NOT_FOUND 발생
Node.js 16, ESM, Windows	import 경로와 실제 파일명의 대소문자 불일치	개발 환경에서는 정상 동작
Next.js 15.1.0, Node.js ESM	cacheHandler: import.meta.resolve(...)가 file:// URL을 반환	개발·빌드에서 .next/file:/... 경로와 함께 실패
Next.js·Vercel, Edge API	@vercel/og가 resvg.simd.wasm을 로드하지 못함	API 경로 호출 시 ERR_MODULE_NOT_FOUND 발생
Node.js 16, ESM, Ubuntu 20.04	Linux의 대소문자 구분 파일 시스템	파일 탐색 실패
Node.js 18, TypeScript ESM 출력	확장자 없는 상대 import	컴파일 후 ERR_MODULE_NOT_FOUND 발생
Node.js 18, ts-node 실행	동일한 확장자 없는 상대 import	문제 미재현

진단 순서

1. [Observation] 오류가 발생한 import가 패키지 import인지 상대 파일 import인지 구분합니다.
2. [Observation] 패키지 import라면 전역 설치와 NODE_PATH에 의존하는지 확인합니다. ESM import는 NODE_PATH를 사용하지 않는 사례가 있습니다.
3. [Observation] 상대 파일 import라면 import 경로의 대소문자와 실제 파일명을 비교합니다. Linux에서는 대소문자 차이가 파일 탐색 실패로 이어질 수 있습니다.
4. [Observation] TypeScript를 컴파일해 실행하는 경우 ts-node가 아니라 출력된 JavaScript를 기준으로 import 경로를 확인합니다.
5. [Observation] ESM 출력 환경에서는 NodeNext 계열 모듈 해석 설정과 상대 import의 .js 확장자 사용 여부를 확인합니다.

[Hypothesis] 위 순서는 입력된 사례의 차이를 기준으로 구성한 진단 순서이며, 모든 ERR_MODULE_NOT_FOUND의 원인을 포함한다고 단정하지 않습니다.