(자바스크립트 완전 정복) Uncaught ReferenceError 정의되지 않은 변수 접근, 원인과 100% 해결법

안녕하세요, 여러분의 코딩 여정을 함께하는 ‘코딩하는곰’입니다. 자바스크립트를 배우거나 개발하다 보면 콘솔에서 만나게 되는 빨간색 에러 메시지, 정말 당황스럽죠? 그중에서도 Uncaught ReferenceError: ... is not defined는 아마 가장 자주 마주치는 에러 중 하나일 겁니다. “분명 변수 이름을 맞게 썼는데?”, “조금 전까지 잘 되던 코드가 왜?”라는 생각이 들며 초조해지기 마련입니다. 하지만 걱정 마세요! 이 에러는 자바스크립트의 기본 개념을 이해하면 금방 해결할 수 있는 친구입니다. 이번 포스팅에서는 ReferenceError가 발생하는 정확한 원인을 파헤치고, 실전에서 바로 적용할 수 있는 해결 방법과 예방 전략까지 자세히 알려드리겠습니다. 에러를 두려워하지 않고, 그것을 이해하는 개발자로 성장하는 첫걸음을 함께 떼어 봅시다.

Uncaught ReferenceError란 무엇인가? 에러의 정체 파악하기

Uncaught ReferenceError는 자바스크립트 엔진이 실행 중인 코드에서 참조(Reference)하려는 변수, 함수, 객체 등의 식별자를 현재 스코프(Scope) 내에서 찾을 수 없을 때 발생하는 런타임 에러입니다. 쉽게 말해, 자바스크립트 엔진이 “너 지금 말한 그 이름, 나 여기서 찾아봤는데 없어!”라고 외치는 거죠. 에러 메시지는 보통 다음과 같은 형태를 띱니다.

Uncaught ReferenceError: myVariable is not defined
Uncaught ReferenceError: sayHello is not defined
Uncaught ReferenceError: Cannot access 'count' before initialization

여기서 Uncaught는 이 에러가 try…catch 문 등으로 ‘잡히지(Caught) 않았다’는 의미입니다. 브라우저 콘솔에 바로 노출되는 에러죠. 이 에러의 핵심은 ‘정의되지 않음(not defined)’ 과 ‘선언되지 않음(undefined)’ 을 구분하는 데 있습니다.

• not defined (ReferenceError): 식별자 자체가 선언된 적이 없습니다. 메모리에 등록조차 되어 있지 않아요.
• undefined: 식별자는 선언되어 메모리에 공간이 할당되었지만, 아무런 값도 할당되지 않은 상태입니다. var a; console.log(a); // undefined 에서의 그것과 같죠. ReferenceError는 전자의 경우에 해당합니다. 이 기본적인 차이를 이해하는 것이 문제 해결의 첫걸음입니다.

🎯 개발자 생산성 향상 방법을 찾고 있다면, (Vue.js & Angular) Cant bind to X 속성 바인딩 오류 완벽 해결 가이드를 참고해보세요.

ReferenceError가 발생하는 5가지 주요 원인과 상세 분석

에러를 고치려면 왜 발생하는지 정확히 알아야 합니다. 다음은 Uncaught ReferenceError를 초래하는 대표적인 시나리오입니다.

1. 변수/함수의 선언 전 접근 (가장 흔한 경우)

가장 기본적이고 흔한 실수입니다. 변수나 함수를 선언(정의)하기도 전에 사용하려고 할 때 발생합니다.

// ❌ 잘못된 예시: 선언 전 사용
console.log(myName); // Uncaught ReferenceError: myName is not defined
let myName = '코딩하는곰';
// ❌ 함수도 마찬가지입니다.
sayHi(); // Uncaught ReferenceError: sayHi is not defined
const sayHi = function() { console.log('Hi!'); };

2. 스코프(Scope) 규칙을 벗어난 접근

변수는 자신이 선언된 스코프({} 중괄호로 묶인 범위) 내에서만 유효합니다. 블록 스코프(let, const)와 함수 스코프(var)의 차이를 이해하지 못하면 이 에러에 빠지기 쉽습니다.

// ❌ 블록 스코프 외부에서 접근
if (true) {
    let blockScopedVar = '안에서만 살아요';
    var functionScopedVar = '함수까지는 살아요';
}
console.log(blockScopedVar); // Uncaught ReferenceError: blockScopedVar is not defined
console.log(functionScopedVar); // '함수까지는 살아요' (에러 안 남)
// ❌ 함수 스코프 외부에서 접근
function myFunction() {
    var localVar = '나는 지역 변수';
}
console.log(localVar); // Uncaught ReferenceError: localVar is not defined

3. 호이스팅(Hoisting)과 TDZ(Temporal Dead Zone)의 함정

자바스크립트는 변수와 함수 선언을 코드의 최상단으로 끌어올리는 ‘호이스팅’ 현상이 있습니다. 하지만 let과 const는 호이스팅되면서도 TDZ라는 구간에 갇혀 선언 전까지 접근할 수 없게 됩니다.

// 호이스팅과 TDZ
console.log(usingVar); // undefined (에러 안 남. 호이스팅됨)
console.log(usingLet); // Uncaught ReferenceError: Cannot access 'usingLet' before initialization
console.log(usingConst); // Uncaught ReferenceError: Cannot access 'usingConst' before initialization
var usingVar = 'Var';
let usingLet = 'Let';
const usingConst = 'Const';

usingLet과 usingConst는 선언은 호이스팅되어 에러 메시지가 “is not defined”가 아닌 “Cannot access … before initialization” 으로 나옵니다. 이는 엔진이 변수의 존재는 알고 있지만, TDZ에 있어 접근을 금지한다는 뜻입니다. var는 TDZ가 없어 undefined 값을 가지게 되죠.

4. 오타(Typos)와 대소문자 구분

간과하기 쉬운 치명적인 원인입니다. 자바스크립트는 식별자의 대소문자를 엄격히 구분합니다.

const userName = 'Gom';
console.log(username); // Uncaught ReferenceError: username is not defined (소문자 'n')
console.log(Username); // Uncaught ReferenceError: Username is not defined (대문자 'U')

5. 외부 라이브러리 로드 실패 또는 순서 문제

HTML에서 자바스크립트 파일을 로드할 때, 라이브러리(jQuery, React 등)가 정의되기 전에 해당 라이브러리를 사용하는 코드가 실행되면 발생합니다.

<!-- ❌ 잘못된 순서 -->
<script src="myApp.js"></script> <!-- 이 안에서 jQuery를 사용함 -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

myApp.js 내의 $(jQuery)는 아직 로드되지 않았기 때문에 ReferenceError가 발생합니다.

최신 당첨번호와 AI 추천 번호를 모두 확인하고 싶다면, QR코드 번호 확인 기능이 있는 지니로또AI 앱이 완벽한 선택입니다.

실전! ReferenceError 100% 해결법 및 예방 전략

원인을 알았으니, 이제 해결하고 미리 방지하는 방법을 알아봅시다.

해결법 1: 선언 후 사용의 원칙 지키기 (기본 중의 기본)

변수나 함수는 반드시 사용하기 전에 선언하는 습관을 들이세요. 코드를 위에서 아래로 읽는 자연스러운 흐름을 따르는 것이 가장 안전합니다.

// ✅ 올바른 예시: 선언 후 사용
let myName = '코딩하는곰';
console.log(myName); // '코딩하는곰'
const sayHi = function() { console.log('Hi!'); };
sayHi(); // 'Hi!'

해결법 2: 스코프 이해하고 설계하기

변수를 어디에서 선언할지 신중히 생각하세요. 특정 블록이나 함수 내에서만 쓰는 변수는 그 안에서 let, const로 선언합니다. 여러 곳에서 공유해야 하는 변수는 적절한 상위 스코프(예: 모듈 상단, 함수 최상단)에서 선언하되, 전역 스코프(window)의 오염은 최소화하세요.

// ✅ 스코프를 고려한 설계
const GLOBAL_CONFIG = { apiUrl: '...' }; // 전역적으로 필요한 설정
function processData(input) {
    const localResult = input * 2; // 함수 내부에서만 사용
    if (localResult > 10) {
        let message = '큰 수'; // if 블록 내부에서만 사용
        console.log(message);
    }
    // console.log(message); // 여기서 쓰면 ReferenceError!
    return localResult;
}

해결법 3: let/const와 TDZ 인지하고, var 사용은 신중히

현대 자바스크립트에서는 var 대신 let과 const를 사용하는 것이 권장됩니다. let과 const의 TDZ는 실수로 선언 전 변수에 접근하는 것을 엄격히 막아줘 더 안전한 코드를 작성할 수 있게 합니다. var의 호이스팅과 함수 스코프는 예상치 못한 버그를 만들 수 있습니다.

// ✅ let/const는 TDZ로 안전장치가 있습니다.
// console.log(safeVar); // 여기서 접근하면 ReferenceError 발생하여 실수 방지!
let safeVar = '안전한 변수';

해결법 4: 철저한 오타 검사와 네이밍 컨벤션

코드 편집기(VS Code, WebStorm 등)의 린터(Linter, ESLint)와 포매터(Prettier)를 활용하세요. ESLint는 no-undef 규칙을 통해 정의되지 않은 변수 사용을 즉시 빨간 줄로 표시해줍니다. 또한, camelCase나 CONSTANT_CASE 같은 일관된 네이밍 컨벤션을 팀과 함께 정하면 오타 가능성을 크게 줄일 수 있습니다.

해결법 5: 의존성 로드 순서 확인 및 모듈 시스템 사용

HTML 파일에서 <script> 태그의 순서를 의존 관계에 맞게 배치하세요. 라이브러리 → 사용자 코드 순으로 로드되어야 합니다. 더 나은 방법은 ES6 모듈(import/export)이나 Webpack, Vite 같은 번들러를 사용하는 것입니다. 이들은 의존성 관리를 자동화하고, 로드 순서 문제를 근본적으로 해결해줍니다.

<!-- ✅ 올바른 순서 -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="myApp.js"></script> <!-- 이제 $를 안전하게 사용 가능 -->

// ✅ ES6 모듈 사용 (myApp.js)
import $ from 'jquery'; // 번들러가 의존성과 순서를 관리해줌.
// ... $ 사용 코드

추가 팁: 개발자 도구를 활용한 디버깅

에러가 발생하면 당황하지 말고 브라우저 개발자 도구(F12)의 ‘콘솔(Console)’ 탭을 보세요. 에러 메시지와 에러가 발생한 파일명 및 줄 번호가 정확히 표시됩니다. 그 줄을 클릭하면 ‘소스(Sources)’ 탭에서 해당 코드 라인으로 바로 이동해 문제를 집중적으로 분석할 수 있습니다. debugger; 키워드를 코드 중간에 삽입하여 실행을 일시 정지시키고 변수 상태를 살펴보는 것도 강력한 방법입니다.

치매 예방과 인지 기능 향상을 위한 앱을 찾고 있다면, AI 기반 힌트와 함께하는 스도쿠 저니를 추천합니다.

지금까지 자바스크립트 개발자의 길목에 반드시 마주치는 Uncaught ReferenceError에 대해 원인부터 해결법, 예방책까지 하나씩 자세히 살펴보았습니다. 이 에러는 결국 자바스크립트의 스코프, 호이스팅, 변수 선언 키워드의 특성에 대한 이해도를 시험하는 문제입니다. 처음에는 에러 메시지가 무섭게 느껴질 수 있지만, 오늘 배운 것처럼 체계적으로 접근하면 결코 두려울 것이 없습니다. 에러는 우리가 놓친 개념을 친절하게(가끔은 무심하게) 알려주는 최고의 선생님입니다. 앞으로 콘솔에 빨간 에러가 나타나도 “아, 이건 아마 스코프 문제구나!” 또는 “TDZ에 걸렸네!”라고 추론하며 차근차근 해결해 나가는 당신의 모습을 상상해 보세요. 그 과정에서 한 층 더 성장한 개발자가 되어 있을 겁니다. 계속해서 코드를 쓰고, 에러를 마주치고, 해결하는 경험을 쌓아가세요. 여러분의 코딩 여정을 응원합니다! 다음 포스팅에서도 유용한 개발 팁으로 찾아뵙겠습니다. 감사합니다.

• 코딩하는곰 드림 -

✅ 요즘 주목받는 건강기능식품 정보가 궁금하다면, 혜당 메모리를 참고해보세요.