ERR_REQUIRE_CYCLE_MODULE
빠른 답변
- 이 오류는 무엇인가요?
- CommonJS와 ES Module 사이의 즉시 순환 의존성으로 require()가 실패할 때 표시되는 Node.js 오류 코드입니다.
- 가장 흔한 원인은 무엇인가요?
- ERR_REQUIRE_CYCLE_MODULE은 require()하려는 ES Module이 CommonJS와 ES Module 사이의 즉시 순환 의존성에 참여할 때 발생하며, 순환에 포함된 require() 호출을 최상위 수준이 아닌 내부 함수에서 지연 실행하면 피할 수 있습니다.
- 무엇을 먼저 확인해야 하나요?
- 오류 객체 또는 로그의 `error.code` 값이 `ERR_REQUIRE_CYCLE_MODULE`과 일치하는지 확인합니다.
현재 증상
- 애플리케이션 오류 메시지
먼저 확인할 항목
오류 객체 또는 로그의 `error.code` 값이 `ERR_REQUIRE_CYCLE_MODULE`과 일치하는지 확인합니다.
순환에 포함된 `require()` 호출이 ES Module 또는 CommonJS 모듈의 최상위 수준에서 실행되는지 확인합니다.
피해야 할 조치
주의
- 변경 전 현재 `require()` 호출 위치와 대상 모듈을 기록합니다.
- 한 번에 한 항목만 변경합니다.
- 오류가 발생하면 기록한 이전 코드 상태로 복구합니다.
환경별 원인과 조치
확인
오류 객체 또는 로그의 error.code 값이 ERR_REQUIRE_CYCLE_MODULE인지 확인합니다. Node.js는 오류 메시지 문자열이 버전 간 변경될 수 있으므로 오류 종류 식별에는 error.code 사용을 안내합니다.
의미
이 오류는 require()하려는 ES Module에 CommonJS와 ES Module 사이의 즉시 순환 의존성이 있을 때 발생합니다. ES Module은 이미 평가 중인 동안 다시 평가할 수 없으므로 이 순환은 허용되지 않습니다.
복구
순환에 포함된 require() 호출이 ES Module의 createRequire() 또는 CommonJS 모듈의 최상위 수준에서 실행되는지 확인합니다. 해당 호출을 내부 함수에서 필요할 때 실행하도록 변경해 즉시 순환을 피합니다.
참고 자료
Node.js · 공식 자료 · 확인 범위: Node.js는 require()하려는 ES Module에 CommonJS→ESM 또는 ESM→CommonJS 즉시 순환 의존성이 있으면 ERR_REQUIRE_CYCLE_MODULE을 발생시킵니다., ES Module은 이미 평가 중일 때 평가할 수 없으므로 이러한 즉시 순환 의존성은 허용되지 않습니다., 순환에 포함된 require() 호출을 ES Module 또는 CommonJS 모듈의 최상위 수준에서 실행하지 않고 내부 함수에서 지연 실행하면 순환을 피할 수 있습니다. · 확인일: 2026-07-24