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`과 일치하는지 확인합니다.
- 적용 범위
- 화면 또는 로그에 같은 오류 메시지·상태명이 표시된 경우문맥: 바이브 코딩
- 출처
- Node.js
- 출처 확인일
- 2026-07-24
- 최종 검토
- 2026-07-24
- 정정 이력
- 2026-07-29 이후 기록 없음
- 관련 기술
이 문서의 범위
현재 증상
- 애플리케이션 오류 메시지
먼저 확인할 항목
오류 객체 또는 로그의 `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