Uncaught ReferenceError란? 자바스크립트 문제 원인과 해결 방법 정리

Uncaught ReferenceError란? 자바스크립트 문제 원인과 해결 방법 정리

자바스크립트로 개발하다 보면 콘솔에서 Uncaught ReferenceError라는 빨간 오류를 한 번쯤 만나게 됩니다. 분명 코드를 작성했는데 갑자기 실행이 멈추면 어디부터 확인해야 할지 막막할 수 있는데요.
 
하지만 Uncaught ReferenceError는 원리를 알고 나면 비교적 빠르게 원인을 찾을 수 있는 오류입니다.
 
오늘은 Uncaught ReferenceError란 무엇인지부터 발생 원인, 실제 해결 방법과 디버깅 순서까지 차근차근 알아보겠습니다.

Uncaught ReferenceError란 무엇일까?

ReferenceError는 현재 코드에서 존재하지 않거나 아직 초기화되지 않은 변수, 함수 등의 식별자를 참조할 때 발생하는 자바스크립트 오류입니다. 쉽게 말하면 자바스크립트 엔진이 “지금 사용하려는 이름을 찾을 수 없다”고 알려주는 것이죠.
 

대표적인 메시지는 Uncaught ReferenceError: xxx is not defined입니다. 여기서 Uncaught는 발생한 예외가 try...catch 등으로 처리되지 않았다는 의미로 이해하면 쉽습니다. MDN에서도 ReferenceError를 현재 스코프에서 존재하지 않거나 아직 초기화되지 않은 변수를 참조할 때 발생하는 오류로 설명하고 있습니다.

console.log(userName);
// Uncaught ReferenceError: userName is not defined

 

위 코드에서는 userName이라는 변수를 선언한 적이 없기 때문에 오류가 발생합니다. 따라서 에러 메시지에 표시된 변수명과 파일, 줄 번호를 먼저 확인하는 것이 문제 해결의 시작입니다.

 
 

ReferenceError 발생 원인, 가장 흔한 5가지

첫 번째 원인은 변수나 함수 이름의 오타입니다. 예를 들어 userName을 선언해 놓고 username처럼 다른 대소문자로 작성하면 자바스크립트에서는 서로 다른 식별자로 판단합니다.

 

두 번째는 선언하지 않은 변수를 사용하는 경우입니다. let, const 등으로 변수를 만들지 않은 상태에서 바로 접근하면 is not defined 오류가 나타날 수 있습니다.

 

세 번째는 스코프(scope) 문제입니다. 함수이나 블록 내부에서 let 또는 const로 선언한 값은 해당 범위를 벗어나면 접근할 수 없습니다.

function showMessage() {
  const message = "안녕하세요";
}
console.log(message);
// ReferenceError: message is not defined

 

네 번째는 let·const 변수를 초기화하기 전에 접근하는 경우입니다. 선언문보다 앞에서 해당 변수에 접근하면 TDZ(Temporal Dead Zone)의 영향으로 Cannot access 'x' before initialization 형태의 ReferenceError가 발생할 수 있습니다.

마지막으로 외부 라이브러리나 자바스크립트 파일의 로드 순서도 확인해야 합니다. 특정 라이브러리에서 제공하는 변수나 함수를 먼저 호출했는데 해당 스크립트가 아직 실행되지 않았다면 ReferenceError가 발생할 수 있습니다.
 
 

Uncaught ReferenceError 해결 방법

해결할 때는 복잡하게 생각하기보다 에러 메시지 → 변수명 → 선언 위치 → 스코프 → 로딩 순서 순으로 살펴보는 것이 좋습니다. 먼저 개발자 도구의 Console에서 어떤 식별자가 not defined 상태인지 확인하세요.

발생 원인	확인 및 해결 방법
변수·함수 이름 오타	대소문자를 포함해 선언한 이름과 동일한지 확인
변수 미선언	사용 전에 let, const 등으로 선언
스코프 문제	선언 위치와 실제 사용하는 범위를 확인
초기화 전 접근	let·const 선언 및 초기화 이후에 접근
외부 스크립트 문제	파일 경로와 로드 성공 여부, 실행 순서를 확인

 

여러 자바스크립트 파일을 함께 사용하는 프로젝트에서는 의존 관계를 확인해야 합니다. 일반 외부 스크립트는 상황에 따라 defer를 활용할 수 있으며, ES Module은 기본적으로 지연 실행되는 특성이 있습니다. 모듈에서 import한 값 역시 해당 모듈의 스코프에 속하기 때문에 무조건 전역 변수처럼 접근할 수 있는 것은 아닙니다.

 
 

ReferenceError와 undefined는 어떻게 다를까?

초보 개발자라면 ReferenceError와 undefined를 혼동하기 쉽습니다. 하지만 둘은 의미가 다릅니다. 선언 자체가 존재하지 않는 식별자를 직접 참조하면 ReferenceError가 발생할 수 있지만, 선언된 변수에 아직 값을 넣지 않았다면 값이 undefined일 수 있습니다.

let userName;
console.log(userName); // undefined
console.log(userAge);
// ReferenceError: userAge is not defined

 

따라서 콘솔에서 undefined가 보인다고 무조건 ReferenceError인 것은 아닙니다. 이 차이를 알아두면 디버깅할 때 문제의 범위를 훨씬 빠르게 좁힐 수 있습니다.

 

Uncaught ReferenceError 예방하는 방법

가장 좋은 해결책은 오류가 생기기 전에 실수를 줄이는 것입니다. 변수와 함수 이름에 일관된 규칙을 사용하고, 가능한 한 선언과 사용 위치를 가깝게 유지해 보세요. ESLint 같은 정적 분석 도구를 활용하는 것도 선언되지 않은 변수 등의 문제를 개발 단계에서 발견하는 데 도움이 됩니다.
 
또한 브라우저 개발자 도구의 Console과 Sources를 적극적으로 활용하는 습관을 들이면 좋습니다. 오류 메시지에 표시된 파일과 줄 번호를 따라가면서 해당 식별자가 어디에서 선언되고 어느 범위에서 사용되는지 확인하면 원인을 빠르게 찾을 수 있습니다.
 
 
지금까지 Uncaught ReferenceError의 의미와 발생 원인, 해결 방법을 살펴봤습니다. 핵심은 “자바스크립트가 현재 위치에서 해당 식별자를 제대로 찾을 수 있는가?”를 확인하는 것입니다. 에러 메시지가 보여도 당황하지 말고 이름, 선언 위치, 스코프, 실행 순서를 차례대로 점검해 보세요.