ERR_UNKNOWN_FILE_EXTENSION
빠른 답변
- 이 오류는 무엇인가요?
- Node.js가 알 수 없거나 지원하지 않는 파일 확장자의 모듈을 로드하려 할 때 발생하는 오류 코드입니다.
- 가장 흔한 원인은 무엇인가요?
- ERR_UNKNOWN_FILE_EXTENSION은 Node.js가 알 수 없거나 지원하지 않는 파일 확장자의 모듈을 로드하려 했음을 나타냅니다.
- 무엇을 먼저 확인해야 하나요?
- 현재 화면 또는 로그의 오류 객체 `code` 값이 `ERR_UNKNOWN_FILE_EXTENSION`과 일치하는지 확인합니다.
현재 증상
- 애플리케이션 오류 메시지
먼저 확인할 항목
현재 화면 또는 로그의 오류 객체 `code` 값이 `ERR_UNKNOWN_FILE_EXTENSION`과 일치하는지 확인합니다.
오류 메시지 문자열이 아닌 오류 코드 일치 여부로 식별합니다.
환경별 원인과 조치
확인
현재 화면 또는 로그의 오류 객체 code 값이 ERR_UNKNOWN_FILE_EXTENSION과 일치하는지 확인합니다.
일치하면 Node.js 공식 문서 기준으로 알 수 없거나 지원하지 않는 파일 확장자의 모듈을 로드하려 한 경우입니다.
오류 메시지 문자열은 버전 사이에 변경될 수 있으므로, 메시지 대신 오류 코드로 식별합니다.
출처
수정 후 다시 확인
서버 오류 원인 구간 확인
서버 오류가 발생하면 먼저 응답 코드와 오류 로그로 서버 측 문제임을 확인하고, 애플리케이션 코드·구성 파일·플러그인·데이터베이스·메모리를 하나씩 분리해 원인 구간을 좁혀야 합니다. 한 부분만 바꾼 뒤 재현 여부를 확인해 인과를 확정합니다.
- 반환된 상태 코드가 5xx인지 확인합니다. 통과 기준은 500 등 서버 오류 응답이 관찰되어 클라이언트가 아닌 서버 측 문제로 좁혀지는 것입니다.
- 서버·애플리케이션 오류 로그(예 debug.log, 서버 error log)에 해당 시각의 오류가 기록됐는지 확인합니다. 통과 기준은 요청 시각과 일치하는 오류 항목을 찾아내는 것입니다.
- 최근 변경분(코드·구성 파일·플러그인·테마)을 되돌리거나 비활성화한 뒤 재현되는지 확인합니다. 통과 기준은 한 번에 한 요소만 바꿔 원인 요소를 특정하는 것입니다.
- 데이터베이스 연결과 애플리케이션 실행(메모리·실행 시간)을 각각 분리해 확인합니다. 통과 기준은 DB 연결 실패와 실행 자원 부족 중 어느 구간인지 구분되는 것입니다.
- 원인으로 지목한 구간만 수정한 뒤 동일 URL을 다시 요청해 5xx가 사라졌는지 확인합니다. 통과 기준은 반복 요청에서 오류가 재현되지 않는 것입니다.
참고 자료
Errors | Node.js v26.5.0 Documentation (새 창에서 열림)
Node.js · 공식 자료 · 확인 범위: Node.js는 알 수 없거나 지원하지 않는 파일 확장자의 모듈을 로드하려 할 때 ERR_UNKNOWN_FILE_EXTENSION을 발생시킵니다., Node.js 오류는 error.message 대신 error.code로 식별하는 것이 가장 안정적입니다. · 확인일: 2026-07-24